uuts

uuts

the library to generate documentation for time series metamodel.

Installation Windows (one-liner)

• Create an emtpy directory and name it for example "uuts"
• Press the following two keys on the keyboard WIN + R, type "cmd" and navigate to the new directory using "cd C:...\uuts"
• 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)

• Create an emtpy directory and name it for example "uuts"
• Create an empty file in the newly created "uuts" directory. Name it "win_01_init.bat".
• 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

• Execute a file by double clicking on it

Installation Linux, macOS

• Create an emtpy directory and name it for example "uuts"
• Open newly created directory
• 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.