robotframework-libtoc 1.2.8__tar.gz → 1.4.0__tar.gz

{robotframework_libtoc-1.2.8 → robotframework_libtoc-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: robotframework-libtoc
-Version: 1.2.8
+Version: 1.4.0
 Summary: Docs and TOC generator for Robot Framework resources and libs
 Home-page: https://github.com/amochin/robotframework-libtoc
 License: Apache-2.0
@@ -13,13 +13,15 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: importlib-resources (>=5.12,<5.13)
 Requires-Dist: robotframework (>=4)
 Description-Content-Type: text/markdown
 
 ## Robot Framework LibTOC
 
 ## What it does
-This tool generates docs using Robot Framework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) for an entire folder with Robot Framework resources/libs and creates a TOC (table of contents) file for them
+This tool generates docs using Robot Framework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) for an entire folder (or multiple folders) with Robot Framework resources/libs and creates a TOC (table of contents) file for them
 
 ## Why use it
 The Robot Framework Libdoc tool normally generates a HTML file for a single keyword library or a resource file.
@@ -34,10 +36,11 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 ![](Screenshot.png)
 
 ## How it works
-- The tool goes through the specified folder with RF resources and it's **direct** subfolders
+- The tool goes through the specified folders with RF resources and it's **direct** subfolders
 - It looks for the **config files** named `.libtoc` which contain items you would like to create docs for:
     1. Paths to resource files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming))
-    2. Installed RF libraries - names and necessary import params like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
+    2. Paths to resources files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming)) inside packages loaded from the pythonpath
+    3. Installed RF libraries - names and necessary import params like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
         > Other libdoc CLI options (e.g. version or name of the output file) are not supported
 - Then it generates the docs using `libdoc` - both for files paths, resolved from the glob patterns, and for the installed libraries. The created HTML files are placed in the **libtoc output_dir** - keeping the original subfolder structure of resources
 - Finally it generates a **TOC (Table of Contents)** HTML page with links to all the generated HTML files.
@@ -50,6 +53,9 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 **/*.resource
 **/*.py
 
+[packages]
+example_package:resources/**/*.resource
+
 [libs]
 # Use RF library names with params - like for libdoc
 SeleniumLibrary
@@ -57,7 +63,7 @@ Remote::http://10.0.0.42:8270
 # You can use environment variables in lib params
 SomeLib::$some_env_var/somepath
 ```
-> The config file must contain at least one of the sections - `[paths]`, `[libs]` or both
+> The config file must contain at least one of the sections - `[paths]`, `[libs]`, `[packages]`
 ## How to install it
 ### System requirements
 - Python >=3.7
@@ -69,7 +75,7 @@ pip install robotframework-libtoc
 
 ## How to use it
 - Create the `.libtoc` config files in the *root of the resources folder* and/or in *direct subfolders* where you need docs to be created.    
-- Run `libtoc`. The last `resources_dir` parameter is mandatory, others are optional:
+- Run `libtoc`. The last `resources_dirs` parameter is mandatory, it takes any number of paths. Other params are optional:
     - `-d, --output_dir`
     - `--config_file`
     - `--toc_file`
@@ -80,15 +86,16 @@ pip install robotframework-libtoc
     Examples:
     ```shell
     libtoc example_resources
+    libtoc 'example_resources/SUT X' 'example_resources/SUT Y'
     libtoc --output_dir docs example_resources
     libtoc --output_dir docs --toc_file MY_SPECIAL_NAME_FOR_DOCS.html example_resources
     libtoc --toc_template MY_CUSTOM_TOC.html --homepage_template MY_CUSTOM_HOMEPAGE.html example_resources
     ```
 
-- Open the created file, e.g. `docs\keyword_docs.html`
+- Open the created file, e.g. `docs/keyword_docs.html`
 
 ## How to change the TOC and the homepage HTML templates
-The default HTML template files are located in the python installation directory (usually something like `<python_dir>\lib\site-packages\robotframework_libtoc`) and can be changed if necessary.   
+The default HTML template files are located in the python installation directory (usually something like `<python_dir>/lib/site-packages/robotframework_libtoc`) and can be changed if necessary.   
 It's also possible to provide custom HTML template files using the `--toc_template` and `--homepage_template` options.
 
 ## How to set the Python Path

{robotframework_libtoc-1.2.8 → robotframework_libtoc-1.4.0}/README.md

@@ -1,7 +1,7 @@
 ## Robot Framework LibTOC
 
 ## What it does
-This tool generates docs using Robot Framework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) for an entire folder with Robot Framework resources/libs and creates a TOC (table of contents) file for them
+This tool generates docs using Robot Framework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) for an entire folder (or multiple folders) with Robot Framework resources/libs and creates a TOC (table of contents) file for them
 
 ## Why use it
 The Robot Framework Libdoc tool normally generates a HTML file for a single keyword library or a resource file.
@@ -16,10 +16,11 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 ![](Screenshot.png)
 
 ## How it works
-- The tool goes through the specified folder with RF resources and it's **direct** subfolders
+- The tool goes through the specified folders with RF resources and it's **direct** subfolders
 - It looks for the **config files** named `.libtoc` which contain items you would like to create docs for:
     1. Paths to resource files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming))
-    2. Installed RF libraries - names and necessary import params like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
+    2. Paths to resources files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming)) inside packages loaded from the pythonpath
+    3. Installed RF libraries - names and necessary import params like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
         > Other libdoc CLI options (e.g. version or name of the output file) are not supported
 - Then it generates the docs using `libdoc` - both for files paths, resolved from the glob patterns, and for the installed libraries. The created HTML files are placed in the **libtoc output_dir** - keeping the original subfolder structure of resources
 - Finally it generates a **TOC (Table of Contents)** HTML page with links to all the generated HTML files.
@@ -32,6 +33,9 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 **/*.resource
 **/*.py
 
+[packages]
+example_package:resources/**/*.resource
+
 [libs]
 # Use RF library names with params - like for libdoc
 SeleniumLibrary
@@ -39,7 +43,7 @@ Remote::http://10.0.0.42:8270
 # You can use environment variables in lib params
 SomeLib::$some_env_var/somepath
 ```
-> The config file must contain at least one of the sections - `[paths]`, `[libs]` or both
+> The config file must contain at least one of the sections - `[paths]`, `[libs]`, `[packages]`
 ## How to install it
 ### System requirements
 - Python >=3.7
@@ -51,7 +55,7 @@ pip install robotframework-libtoc
 
 ## How to use it
 - Create the `.libtoc` config files in the *root of the resources folder* and/or in *direct subfolders* where you need docs to be created.    
-- Run `libtoc`. The last `resources_dir` parameter is mandatory, others are optional:
+- Run `libtoc`. The last `resources_dirs` parameter is mandatory, it takes any number of paths. Other params are optional:
     - `-d, --output_dir`
     - `--config_file`
     - `--toc_file`
@@ -62,15 +66,16 @@ pip install robotframework-libtoc
     Examples:
     ```shell
     libtoc example_resources
+    libtoc 'example_resources/SUT X' 'example_resources/SUT Y'
     libtoc --output_dir docs example_resources
     libtoc --output_dir docs --toc_file MY_SPECIAL_NAME_FOR_DOCS.html example_resources
     libtoc --toc_template MY_CUSTOM_TOC.html --homepage_template MY_CUSTOM_HOMEPAGE.html example_resources
     ```
 
-- Open the created file, e.g. `docs\keyword_docs.html`
+- Open the created file, e.g. `docs/keyword_docs.html`
 
 ## How to change the TOC and the homepage HTML templates
-The default HTML template files are located in the python installation directory (usually something like `<python_dir>\lib\site-packages\robotframework_libtoc`) and can be changed if necessary.   
+The default HTML template files are located in the python installation directory (usually something like `<python_dir>/lib/site-packages/robotframework_libtoc`) and can be changed if necessary.   
 It's also possible to provide custom HTML template files using the `--toc_template` and `--homepage_template` options.
 
 ## How to set the Python Path

{robotframework_libtoc-1.2.8 → robotframework_libtoc-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "robotframework-libtoc"
-version = "1.2.8"
+version = "1.4.0"
 description = "Docs and TOC generator for Robot Framework resources and libs"
 authors = ["Andre Mochinin"]
 license = "Apache-2.0"
@@ -11,6 +11,7 @@ include = ["robotframework_libtoc/*template.html"]
 [tool.poetry.dependencies]
 python = ">=3.7"
 robotframework = ">=4"
+importlib-resources = "~5.12"
 
 [tool.poetry.scripts]
 libtoc = "robotframework_libtoc.libtoc:main"

robotframework_libtoc-1.4.0/robotframework_libtoc/libtoc.py

@@ -0,0 +1,400 @@
+import argparse
+import glob
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import importlib_resources
+import robot.libdoc
+
+
+class LibdocException(Exception):
+    def __init__(self, broken_file):
+        self.broken_file = broken_file
+
+
+def toc(links, timestamp, home_page_path, template_file=""):
+    """
+    Returns a HTML source code for TOC (table of contents) page, based on the template and including
+    the provided `links`, generation `timestamp` and the `home_page_path` HTML file as a landing page.
+    """
+    if template_file == "":
+        template_file = os.path.join(os.path.dirname(__file__), "toc_template.html")
+    with open(template_file, encoding="utf8") as f:
+        html_template = f.read()
+
+    # double all brackets to make the further formatting work
+    html_with_escaped_braces = html_template.replace("{", "{{")
+    html_with_escaped_braces = html_with_escaped_braces.replace("}", "}}")
+
+    # and convert the formatting brackets back
+    html_with_escaped_braces = html_with_escaped_braces.replace("{{}}", "{}")
+
+    return html_with_escaped_braces.format(home_page_path, links, timestamp)
+
+
+def homepage(timestamp, template_file=""):
+    """
+    Returns a HTML source code for a landing page, based on the template and includig the provided `timestamp`.
+    """
+    if template_file == "":
+        template_file = os.path.join(
+            os.path.dirname(__file__), "homepage_template.html"
+        )
+    with open(template_file, encoding="utf_8") as f:
+        html_template = f.read()
+    return html_template.format(timestamp)
+
+
+def read_config(config_file):
+    """
+    Parses the content of the `config_file` and returns a dictionary `{"paths":[values], "libs":[values]}`.
+
+    The `paths` values are glob patterns, which can be resolved in real paths and used for generating docs using `libdoc`.
+    The `libs`  values are names of Robot Framework libraries with necessary import params - in the way to be also used for docs generation using `libdoc`.
+
+    The config file must be formatted like this:
+    ```
+    # Comments starting with # are ignored
+    [Paths]
+    *.resource
+    **/my_subfolder/*.py
+
+    [Libs]
+    SeleniumLibrary
+    SomeLibrary::some_import_param
+    ```
+    """
+    sections = {
+        "paths": {"markers": ["[paths]"], "values": []},
+        "packages": {"markers": ["[packages]"], "values": []},
+        "libs": {"markers": ["[libs]", "[libraries]"], "values": []},
+    }
+
+    with open(config_file, encoding="utf8") as f:
+        section_to_add = ""
+        lines = f.readlines()
+        for line in lines:
+            stripped_line = line.strip()
+            if len(stripped_line) > 0:
+                if not stripped_line.startswith("#"):  # comments
+                    skip_line = False
+                    for section_name, section_content in sections.items():
+                        if stripped_line.lower() in section_content["markers"]:
+                            section_to_add = section_name
+                            skip_line = True
+                            break
+                    if not skip_line and section_to_add:
+                        sections[section_to_add]["values"].append(stripped_line)
+
+    return {
+        "paths": sections["paths"]["values"],
+        "packages": sections["packages"]["values"],
+        "libs": sections["libs"]["values"],
+    }
+
+
+def add_files_from_folder(folder, base_dir_path, root=True):
+    """
+    Creates a HTML source code with links to all HTML files in the `folder` and all it's subfolders.
+    The links contain file paths relative to the `base_dir_path`.
+
+    The `root` parameter is needed for internal usage only - it's set to False during deeper recursive calls.
+    """
+    result_str = ""
+    if not root:  # means we're in the root - no collapsible need in this case
+        result_str += """<button class="collapsible">{}</button>
+        """.format(
+            os.path.basename(folder)
+        )
+
+        result_str += """<div class="collapsible_content">
+        """
+
+    for item in os.listdir(folder):
+        item_path = os.path.abspath(os.path.join(folder, item))
+        if item.endswith(".html"):
+            name_without_ext = os.path.splitext(item)[0]
+            result_str += """<a class="link_not_selected" href="{}" target="targetFrame">{}</a>
+            """.format(
+                os.path.relpath(item_path, base_dir_path), name_without_ext
+            )
+        else:
+            if os.path.isdir(item_path):
+                result_str += add_files_from_folder(
+                    item_path, base_dir_path, root=False
+                )
+
+    if not root:
+        # end of the "collapsible_content"
+        result_str += """</div>
+    """
+    return result_str
+
+
+def create_docs_for_dir(resource_dir, output_dir, config_file):
+    """
+    Creates HTML docs using Robot Framework module `libdoc` for all resources and libraries in the `resource_dir`.
+    Generated files are placed inside the `output_dir`, keeping the original subfolder tree structure.
+
+    Paths of resource/python files and libraries, which the docs should be generated for, are configured using the `config_file`.
+
+    The `config_file` must be formatted like this:
+    ```
+    # Comments starting with # are ignored
+    [Paths]
+    *.resource
+    **/my_subfolder/*.py
+
+    [Libs]
+    SeleniumLibrary
+    SomeLibrary::some_import_param
+    ```
+    """
+    target_dir = os.path.join(
+        os.path.abspath(output_dir), os.path.basename(resource_dir)
+    )
+    doc_config = read_config(config_file)
+
+    resource_path_patterns = doc_config["paths"]
+    if resource_path_patterns:
+        print(">> Processing paths")
+    broken_files = []
+    for path_pattern in resource_path_patterns:
+        for real_path in glob.glob(
+            os.path.join(resource_dir, path_pattern), recursive=True
+        ):
+            relative_path = os.path.relpath(real_path, resource_dir)
+            target_path = os.path.join(
+                target_dir, relative_path.rpartition(".")[0] + ".html"
+            )
+            print(f">>> Processing file: {relative_path}")
+            return_code = robot.libdoc.libdoc(real_path, target_path, quiet=True)
+            if return_code > 0:
+                broken_files.append(relative_path)
+
+    package_definitions = doc_config["packages"]
+    if package_definitions:
+        print("---")
+    packages = {}
+    broken_packages = []
+    for package_definition in package_definitions:
+        package_name, path_pattern = package_definition.split(":", 1)
+        if package_name not in packages:
+            packages[package_name] = []
+        packages[package_name].append(path_pattern)
+
+    for package_name, paths_patterns in packages.items():
+        print(f">> Processing package: {package_name}")
+        try:
+            package_anchor = importlib_resources.files(package_name)
+        except ModuleNotFoundError as e:
+            print(f"Importing package '{package_name}' failed: {e}")
+            broken_packages.append(package_name)
+        else:
+            with importlib_resources.as_file(package_anchor) as package_path:
+                for path_pattern in paths_patterns:
+                    package_resource_files = package_path.glob(path_pattern)
+                    for real_path in package_resource_files:
+                        relative_path = Path(package_name) / real_path.relative_to(
+                            package_path
+                        )
+                        target_path = os.path.join(
+                            target_dir, relative_path.with_suffix(".html")
+                        )
+                        print(f">>> Processing file: {relative_path}")
+                        return_code = robot.libdoc.libdoc(
+                            real_path, target_path, quiet=True
+                        )
+                        if return_code > 0:
+                            broken_packages.append(relative_path)
+
+    libs = doc_config["libs"]
+    if libs:
+        print("---")
+        print(">> Processing libraries")
+    broken_libs = []
+    for lib in libs:
+        lib_str_with_resolved_vars = os.path.expandvars(lib)
+        target_path = os.path.join(
+            target_dir, lib_str_with_resolved_vars.partition("::")[0] + ".html"
+        )
+        print(f">>> Processing lib: {lib_str_with_resolved_vars}")
+        return_code = robot.libdoc.libdoc(
+            lib_str_with_resolved_vars, target_path, quiet=True
+        )
+        if return_code > 0:
+            broken_libs.append(lib_str_with_resolved_vars)
+    return broken_files, broken_packages, broken_libs
+
+
+def create_toc(
+    html_docs_dir,
+    toc_file="keyword_docs.html",
+    homepage_file="homepage.html",
+    toc_template="",
+    homepage_template="",
+):
+    """
+    Generates a `toc_file` (Table of Contents) HTML page with links to all HTML files inside the `html_docs_dir` and all it's subfolders.
+
+    The navigation tree structure in the TOC repeats the folder tree structure.
+    It also creates a `homepage_file` shown as a landing page when opening the TOC.
+
+    All the content of the `html_docs_dir` will be moved in the new `src` subfolder, leaving only the `toc_file` directly inside.
+    """
+    print(f"> Creating TOC in: {os.path.abspath(html_docs_dir)}")
+    # move all subfolders and files into "src"
+    src_subdir = os.path.join(html_docs_dir, "src")
+    os.makedirs(src_subdir, exist_ok=True)
+    all_docs = os.listdir(html_docs_dir)
+    for doc_element in all_docs:
+        if doc_element == "src":
+            continue
+        src = os.path.join(html_docs_dir, doc_element)
+        target = os.path.join(src_subdir, doc_element)
+        shutil.move(src, target)
+
+    # create homepage in "src"
+    homepage_path = os.path.join(src_subdir, homepage_file)
+    current_date_time = datetime.now().strftime("%d.%m.%Y %H:%M:%S")
+    doc_files_links = add_files_from_folder(src_subdir, os.path.abspath(html_docs_dir))
+    with open(homepage_path, "w", encoding="utf8") as f:
+        f.write(homepage(current_date_time, homepage_template))
+
+    # create TOC
+    toc_file_path = os.path.join(html_docs_dir, toc_file)
+    with open(toc_file_path, "w", encoding="utf8") as f:
+        f.write(
+            toc(
+                doc_files_links,
+                current_date_time,
+                os.path.relpath(homepage_path, os.path.abspath(html_docs_dir)),
+                toc_template,
+            )
+        )
+
+    print("---")
+    print("TOC finished. Output file: {}".format(os.path.abspath(toc_file_path)))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generates keyword docs using libdoc based on config files in direct subfolders of the resources dir and creates a TOC"
+    )
+    parser.add_argument(
+        "resources_dirs", nargs="+", help="Folders with resources and keywords files"
+    )
+    parser.add_argument(
+        "-d", "--output_dir", default="docs", help="Folder to create the docs in"
+    )
+    parser.add_argument(
+        "--config_file",
+        default=".libtoc",
+        help="File in each folder with docs generation configs",
+    )
+    parser.add_argument(
+        "--toc_file", default="keyword_docs.html", help="Name of the TOC file generated"
+    )
+    parser.add_argument(
+        "--toc_template", default="", help="Custom HTML template for the TOC file"
+    )
+    parser.add_argument(
+        "--homepage_template",
+        default="",
+        help="Custom HTML template for the homepage file",
+    )
+    parser.add_argument(
+        "-P",
+        "--pythonpath",
+        default="",
+        help="Additional locations where to search for libraries and resources similarly as when running tests",
+    )
+
+    args = parser.parse_args()
+
+    if args.pythonpath:
+        sys.path.insert(0, args.pythonpath)
+
+    if os.path.isdir(args.output_dir):
+        print(f"Output dir already exists, deleting it: {args.output_dir}")
+        shutil.rmtree(args.output_dir)
+    total_broken_files = []
+    total_broken_packages = []
+    total_broken_libs = []
+
+    for resources_dir in args.resources_dirs:
+        print("")
+        print(f"> Creating docs for dir: {os.path.abspath(resources_dir)}")
+        for child_element in os.listdir(resources_dir):
+            child_element_path = os.path.join(resources_dir, child_element)
+            current_broken_files = []
+            current_broken_packages = []
+            current_broken_libs = []
+            if os.path.isdir(child_element_path):
+                config_file = os.path.join(child_element_path, args.config_file)
+                if os.path.isfile(config_file):
+                    (
+                        current_broken_files,
+                        current_broken_packages,
+                        current_broken_libs,
+                    ) = create_docs_for_dir(
+                        child_element_path,
+                        args.output_dir,
+                        os.path.abspath(config_file),
+                    )
+            elif child_element == args.config_file:
+                current_broken_files, current_broken_packages, current_broken_libs = (
+                    create_docs_for_dir(
+                        resources_dir,
+                        args.output_dir,
+                        os.path.abspath(os.path.join(resources_dir, args.config_file)),
+                    )
+                )
+
+            total_broken_files += current_broken_files
+            total_broken_packages += current_broken_packages
+            total_broken_libs += current_broken_libs
+
+    if total_broken_files:
+        print("")
+        print(
+            f"---> !!! Errors occurred while generating docs for {len(total_broken_files)} files (see details above):"
+        )
+        for f in total_broken_files:
+            print(f"         - {f}")
+
+    if total_broken_packages:
+        print("")
+        print(
+            f"---> !!! Errors occurred while generating docs for {len(total_broken_packages)} packages (see details above):"
+        )
+        for f in total_broken_packages:
+            print(f"         - {f}")
+
+    if total_broken_libs:
+        print("")
+        print(
+            f"---> !!! Errors occurred while generating docs for {len(total_broken_libs)} libs (see details above):"
+        )
+        for l in total_broken_libs:
+            print(f"         - {l}")
+
+    if os.path.isdir(args.output_dir):
+        print("")
+        create_toc(
+            args.output_dir,
+            args.toc_file,
+            toc_template=args.toc_template,
+            homepage_template=args.homepage_template,
+        )
+    else:
+        print("No docs were created!")
+
+    print("")
+
+
+if __name__ == "__main__":
+    main()

robotframework_libtoc-1.2.8/robotframework_libtoc/libtoc.py

@@ -1,251 +0,0 @@
-import os
-import sys
-import shutil
-import glob
-import argparse
-from datetime import datetime
-import robot.libdoc
-
-class LibdocException(Exception):
-    def __init__(self, broken_file):
-        self.broken_file = broken_file
-
-def toc(links, timestamp, home_page_path, template_file=""):
-    """
-    Returns a HTML source code for TOC (table of contents) page, based on the template and including
-    the provided `links`, generation `timestamp` and the `home_page_path` HTML file as a landing page.
-    """
-    if template_file == "":
-        template_file = os.path.join(os.path.dirname(__file__), "toc_template.html")
-    with open(template_file, encoding="utf8") as f:
-        html_template = f.read()
-
-    # double all brackets to make the further formatting work
-    html_with_escaped_braces = html_template.replace('{', '{{')
-    html_with_escaped_braces = html_with_escaped_braces.replace('}', '}}')
-
-    # and convert the formatting brackets back
-    html_with_escaped_braces = html_with_escaped_braces.replace('{{}}', '{}')
-
-    return html_with_escaped_braces.format(home_page_path, links, timestamp)
-
-def homepage(timestamp, template_file=""):
-    """
-    Returns a HTML source code for a landing page, based on the template and includig the provided `timestamp`.
-    """
-    if template_file == "":
-        template_file = os.path.join(os.path.dirname(__file__), "homepage_template.html")
-    with open(template_file, encoding="utf_8") as f:
-        html_template = f.read()
-    return html_template.format(timestamp)
-
-def read_config(config_file):
-    """
-    Parses the content of the `config_file` and returns a dictionary `{"paths":[values], "libs":[values]}`.
-    
-    The `paths` values are glob patterns, which can be resolved in real paths and used for generating docs using `libdoc`.
-    The `libs`  values are names of Robot Framework libraries with necessary import params - in the way to be also used for docs generation using `libdoc`.
-
-    The config file must be formatted like this:    
-    ```
-    # Comments starting with # are ignored
-    [Paths]
-    *.resource
-    **/my_subfolder/*.py
-
-    [Libs]
-    SeleniumLibrary
-    SomeLibrary::some_import_param
-    ```
-    """
-    sections = {
-        "paths": {"markers":["[paths]"], "values":[]},
-        "libs":  {"markers": ["[libs]", "[libraries]"], "values":[]}
-    }
-    
-    with open(config_file, encoding="utf8") as f:
-        section_to_add = ""
-        lines = f.readlines()        
-        for line in lines:
-            stripped_line = line.strip()
-            if len(stripped_line) > 0:
-                if not stripped_line.startswith('#'):  # comments
-                    skip_line = False
-                    for section_name, section_content in sections.items():
-                        if stripped_line.lower() in section_content["markers"]:
-                            section_to_add = section_name
-                            skip_line = True
-                            break
-                    if not skip_line and section_to_add:
-                        sections[section_to_add]["values"].append(stripped_line)
-    
-    return {"paths": sections["paths"]["values"], "libs": sections["libs"]["values"]}
-
-def add_files_from_folder(folder, base_dir_path, root=True):
-    """
-    Creates a HTML source code with links to all HTML files in the `folder` and all it's subfolders.    
-    The links contain file paths relative to the `base_dir_path`.
-    
-    The `root` parameter is needed for internal usage only - it's set to False during deeper recursive calls.
-    """
-    result_str = ""
-    if not root:  # means we're in the root - no collapsible need in this case
-        result_str += """<button class="collapsible">{}</button>
-        """.format(os.path.basename(folder))
-
-        result_str += """<div class="collapsible_content">
-        """
-
-    for item in os.listdir(folder):
-        item_path = os.path.abspath(os.path.join(folder, item))
-        if item.endswith(".html"):
-            name_without_ext = os.path.splitext(item)[0]            
-            result_str += """<a class="link_not_selected" href="{}" target="targetFrame">{}</a>
-            """.format(os.path.relpath(item_path, base_dir_path), name_without_ext)
-        else:
-            if os.path.isdir(item_path):
-                result_str += add_files_from_folder(item_path, base_dir_path, root=False)
-
-    if not root:
-        # end of the "collapsible_content"
-        result_str += """</div>
-    """
-    return result_str
-
-def create_docs_for_dir(resource_dir, output_dir, config_file):
-    """
-    Creates HTML docs using Robot Framework module `libdoc` for all resources and libraries in the `resource_dir`.
-    Generated files are placed inside the `output_dir`, keeping the original subfolder tree structure.
-
-    Paths of resource/python files and libraries, which the docs should be generated for, are configured using the `config_file`.
-
-    The `config_file` must be formatted like this:    
-    ```
-    # Comments starting with # are ignored
-    [Paths]
-    *.resource
-    **/my_subfolder/*.py
-
-    [Libs]
-    SeleniumLibrary
-    SomeLibrary::some_import_param
-    ```
-    """
-    target_dir = os.path.join(os.path.abspath(output_dir), os.path.basename(resource_dir))
-    doc_config = read_config(config_file)
-    
-    resource_path_patterns = doc_config["paths"]
-    broken_files = []
-    for path_pattern in resource_path_patterns:
-        for real_path in glob.glob(os.path.join(resource_dir, path_pattern), recursive=True):
-            relative_path = os.path.relpath(real_path, resource_dir)
-            target_path = os.path.join(target_dir, relative_path.rpartition('.')[0] + ".html")
-            print(f">> Generating docs for resource: {relative_path}")
-            return_code = robot.libdoc.libdoc(real_path, target_path)
-            if return_code > 0:
-                broken_files.append(relative_path)
-
-    libs = doc_config["libs"]
-    broken_libs = []
-    for lib in libs:
-        lib_str_with_resolved_vars = os.path.expandvars(lib)
-        target_path = os.path.join(target_dir, lib_str_with_resolved_vars.partition("::")[0] + ".html")
-        print(f">> Generating docs for library: {lib_str_with_resolved_vars}") 
-        return_code = robot.libdoc.libdoc(lib_str_with_resolved_vars, target_path)
-        if return_code > 0:
-            broken_libs.append(lib_str_with_resolved_vars)
-    return broken_files, broken_libs
-
-def create_toc(html_docs_dir, toc_file="keyword_docs.html", homepage_file="homepage.html", toc_template="", homepage_template=""):
-    """
-    Generates a `toc_file` (Table of Contents) HTML page with links to all HTML files inside the `html_docs_dir` and all it's subfolders.
-
-    The navigation tree structure in the TOC repeats the folder tree structure.
-    It also creates a `homepage_file` shown as a landing page when opening the TOC.
-
-    All the content of the `html_docs_dir` will be moved in the new `src` subfolder, leaving only the `toc_file` directly inside.
-    """
-    print(f">>> Creating TOC in: {os.path.abspath(html_docs_dir)}")    
-    # move all subfolders and files into "src"
-    src_subdir = os.path.join(html_docs_dir, "src")
-    os.makedirs(src_subdir, exist_ok=True)
-    all_docs = os.listdir(html_docs_dir)
-    for doc_element in all_docs:
-        if doc_element == "src":
-            continue
-        src = os.path.join(html_docs_dir, doc_element)
-        target = os.path.join(src_subdir, doc_element)
-        shutil.move(src, target)
-    
-    # create homepage in "src"
-    homepage_path = os.path.join(src_subdir, homepage_file)
-    current_date_time = datetime.now().strftime('%d.%m.%Y %H:%M:%S')
-    doc_files_links = add_files_from_folder(src_subdir, os.path.abspath(html_docs_dir))
-    with open(homepage_path, 'w', encoding="utf8") as f:
-        f.write(homepage(current_date_time, homepage_template))
-
-    # create TOC
-    toc_file_path = os.path.join(html_docs_dir, toc_file)
-    with open(toc_file_path, 'w', encoding="utf8") as f:
-        f.write(toc(doc_files_links, current_date_time, os.path.relpath(homepage_path, os.path.abspath(html_docs_dir)), toc_template))
-    
-    print("TOC finished. Output file: {}".format(os.path.abspath(toc_file_path)))
-
-def main():
-    parser = argparse.ArgumentParser(description="Generates keyword docs using libdoc based on config files in direct subfolders of the resources dir and creates a TOC")
-    parser.add_argument("resources_dir", help="Folder with resources and keywords files")
-    parser.add_argument("-d", "--output_dir", default="docs", help="Folder to create the docs in")
-    parser.add_argument("--config_file", default=".libtoc", help="File in each folder with docs generation configs")
-    parser.add_argument("--toc_file", default="keyword_docs.html", help="Name of the TOC file generated")
-    parser.add_argument("--toc_template", default="", help = "Custom HTML template for the TOC file")
-    parser.add_argument("--homepage_template", default="", help = "Custom HTML template for the homepage file")
-    parser.add_argument("-P", "--pythonpath", default="", help="Additional locations where to search for libraries and resources similarly as when running tests")
-
-    args = parser.parse_args()
-
-    if args.pythonpath:
-        sys.path.insert(0, args.pythonpath)
-
-    print(f"Creating docs for: {os.path.abspath(args.resources_dir)}")
-
-    if os.path.isdir(args.output_dir):
-        print(f"Output dir already exists, deleting it: {args.output_dir}")
-        shutil.rmtree(args.output_dir)
-    total_broken_files = []
-    total_broken_libs = []
-    for child_element in os.listdir(args.resources_dir):                
-        child_element_path = os.path.join(args.resources_dir, child_element)
-        current_broken_files = []
-        current_broken_libs = []
-        if os.path.isdir(child_element_path):
-            config_file = os.path.join(child_element_path, args.config_file)
-            if os.path.isfile(config_file):
-                current_broken_files, current_broken_libs = create_docs_for_dir(child_element_path, args.output_dir, os.path.abspath(config_file))
-        elif child_element == args.config_file:
-            current_broken_files, current_broken_libs = create_docs_for_dir(args.resources_dir, args.output_dir, os.path.abspath(os.path.join(args.resources_dir, args.config_file)))
-        
-        total_broken_files +=  current_broken_files
-        total_broken_libs += current_broken_libs
-    
-    if total_broken_files:
-        print("")
-        print(f"---> !!! Errors occurred while generating docs for {len(total_broken_files)} files (see details above):")
-        for f in total_broken_files:
-            print(f"         - {f}")
-
-    if total_broken_libs:
-        print("")
-        print(f"---> !!! Errors occurred while generating docs for {len(total_broken_libs)} libs (see details above):")
-        for l in total_broken_libs:
-            print(f"         - {l}")
-
-    if os.path.isdir(args.output_dir):
-        print("")
-        create_toc(args.output_dir, args.toc_file, toc_template=args.toc_template, homepage_template=args.homepage_template)
-    else:
-        print("No docs were created!")
-
-    print("")
-
-if __name__ == "__main__":
-    main()