uuts 1.0.27

uuts library for Time Series Metamodel documentation generation

uuts

the library to generate documentation for time series metamodel.

Installation Windows (one-liner)

1. Create an emtpy directory and name it for example "uuts"
2. Press the following two keys on the keyboard WIN + R, type "cmd" and navigate to the new directory using "cd C:...\uuts"
3. Type the following command and execute it:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" && set Path=C:\Users\User\.local\bin;%Path% && uv init && uv add uuts && uv sync --upgrade && uv run python -c "import uuts.init"

Sometimes it is necessary to restart the terminal and run the command above again to make the changes take effect.

Installation Windows (using init.bat)

1. Create an emtpy directory and name it for example "uuts"
2. Create an empty file in the newly created "uuts" directory. Name it "win_01_init.bat".
3. Copy the following text into the file "win_01_init.bat":

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
set Path=C:\Users\User\.local\bin;%Path% 
uv init 
uv add uuts
uv lock --upgrade
pause

4. Execute a file by double clicking on it

Installation Linux, macOS

1. Create an emtpy directory and name it for example "uuts"
2. Open newly created directory
3. Run the following commands:

curl -LsSf https://astral.sh/uv/install.sh | sh
echo "or use wget if there is a problem with curl"
wget -qO- https://astral.sh/uv/install.sh | sh
uv init 
uv add uuts

How to use the uuts

Create a new file in the "uuts" directory. Name it "run.bat" or "run.sh". Copy the following text into the file "run.bat" or "run.sh":

uv run main.py --action "generateDocumentation" --input "C:\git\cams\Toolkit\metamodel\deploy\etrm" --output "./" --language "cs"

Create a main.py file with following code:

from uuts import generateDocumentation
import uuts.documentation as tsdoc
from pathlib import Path
import sys
import argparse


class MyParser(argparse.ArgumentParser):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs) 
    
    def error(self, message):
        self.print_help(sys.stderr)
        self.exit(2, '%s: error: %s\n' % (self.prog, message))

    def _check_directory_exists(self, value: str) -> bool:
        """
        Validates and returns the absolute path to the output directory.
        """
        path = Path(value.rstrip("/\\"))
        path = path.resolve()
        return path.exists()

    def _input_str(self, value: str) -> str:
        """
        Validates and returns the absolute path to the input directory.
        """
        if self._check_directory_exists(value):
            return str(value)
        else:
            raise argparse.ArgumentTypeError(f"Input directory {value} does not exist")


    def _output_str(self, value: str) -> str:
        """
        Validates and returns the absolute path to the output directory.
        """
        if self.args.action == "generateDocumentation":
            if self._check_directory_exists(value):
                return str(value)
            else:
                raise argparse.ArgumentTypeError(f"Output directory {value} does not exist")
        else:
            raise argparse.ArgumentTypeError(f"--output is not required for action {self.args.action} but was provided")
        
    def validate_args(self, args):
        """
        Validates the command-line arguments.
        """
        if args.action == "generateDocumentation":
            if not self._check_directory_exists(args.input):
                raise argparse.ArgumentTypeError(f"Input directory {args.input} does not exist")
            if not self._check_directory_exists(args.output):
                raise argparse.ArgumentTypeError(f"Output directory {args.output} does not exist")
        else:
            raise argparse.ArgumentTypeError(f"Unknown action {args.action}. Action was not implemented.")
        

def main():
    """
    Main function to generate documentation for the Time Series Metamodel.
    Parses command-line arguments and initiates the documentation generation process.
    """
    parser = MyParser(
        description='Documentation generator for Time Series Metamodel.',
        epilog="Example: uv run generatedoc.py --action \"generateDocumentation\" --input \"absolute_path_to_metamodel.zip\" "
               "--output \"absolute_path_to_output_directory\" --language \"cs\""
    )
    parser.add_argument('--action', type=str, required=True, help='Action to perform. Either "generateDocumentation" to generate documentation or "analyzeImpact" to run analyzeImpact of the metamodel or "analyzeImpactAndDeploy" to run analyzeImpact and deploy procedure')
    parser.add_argument('--input', type=str, required=True, help='Path to the metamodel zip file or metamodel directory.')
    parser.add_argument('--output', type=str, required=False, default='./', help='Path to the output documentation directory. (default: "./")')
    parser.add_argument('--language', type=str, required=False, default='en', help='Language code for the documentation (default: "en").')
    parser.add_argument('--pages', type=str, required=False, default='', help='List of urls of pages used in case there '
                         'are so many tsdefinitions that the documentation needs to be split into '
                         'multiple pages. (default: "") Example: "book/page?code=4532154,book/page?code=56476")')
    # Parse arguments
    args = parser.parse_args(sys.argv[1:])
    parser.validate_args(args)
    page_urls = []
    if args.pages:
        page_urls = args.pages.split(',')
    # Set up paths
    metamodel_path = Path(args.input)
    output_path = Path(args.output.rstrip("/\\"))
    print(f'Generating documentation from "{str(metamodel_path.resolve())}" '
          f'to "{str(output_path.resolve())}" in language "{args.language}"')
    # Generate documentation
    documentation = tsdoc.Documentation(metamodel_path, output_path)
    documentation.generate_documentation(language=args.language, page_urls=page_urls)
    print(f'\nOK - documentation successfully generated\nSee "{str(output_path.resolve())}"\n')

if __name__ == "__main__":
    main()
    exit(0)

Run the file by double clicking on it or by running it in the terminal.