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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: robotframework-libtoc
-Version: 1.3.0
+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,6 +13,8 @@ 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
 
@@ -37,7 +39,8 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 - 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

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

@@ -19,7 +19,8 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 - 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

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "robotframework-libtoc"
-version = "1.3.0"
+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.3.0 → robotframework_libtoc-1.4.0}/robotframework_libtoc/libtoc.py

@@ -1,15 +1,20 @@
+import argparse
+import glob
 import os
-import sys
 import shutil
-import glob
-import argparse
+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
@@ -21,32 +26,36 @@ def toc(links, timestamp, home_page_path, template_file=""):
         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('}', '}}')
+    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('{{}}', '{}')
+    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")
+        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:    
+    The config file must be formatted like this:
     ```
     # Comments starting with # are ignored
     [Paths]
@@ -59,17 +68,18 @@ def read_config(config_file):
     ```
     """
     sections = {
-        "paths": {"markers":["[paths]"], "values":[]},
-        "libs":  {"markers": ["[libs]", "[libraries]"], "values":[]}
+        "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()        
+        lines = f.readlines()
         for line in lines:
             stripped_line = line.strip()
             if len(stripped_line) > 0:
-                if not stripped_line.startswith('#'):  # comments
+                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"]:
@@ -78,20 +88,27 @@ def read_config(config_file):
                             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"]}
+
+    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.    
+    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))
+        """.format(
+            os.path.basename(folder)
+        )
 
         result_str += """<div class="collapsible_content">
         """
@@ -99,12 +116,16 @@ def add_files_from_folder(folder, base_dir_path, root=True):
     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]            
+            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)
+            """.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)
+                result_str += add_files_from_folder(
+                    item_path, base_dir_path, root=False
+                )
 
     if not root:
         # end of the "collapsible_content"
@@ -112,6 +133,7 @@ def add_files_from_folder(folder, base_dir_path, root=True):
     """
     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`.
@@ -119,7 +141,7 @@ def create_docs_for_dir(resource_dir, output_dir, config_file):
 
     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:    
+    The `config_file` must be formatted like this:
     ```
     # Comments starting with # are ignored
     [Paths]
@@ -131,32 +153,90 @@ def create_docs_for_dir(resource_dir, output_dir, config_file):
     SomeLibrary::some_import_param
     ```
     """
-    target_dir = os.path.join(os.path.abspath(output_dir), os.path.basename(resource_dir))
+    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):
+        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}")
+            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">> Generating docs for library: {lib_str_with_resolved_vars}") 
-        return_code = robot.libdoc.libdoc(lib_str_with_resolved_vars, target_path, quiet=True)
+        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_libs
+    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=""):
+
+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.
 
@@ -165,7 +245,7 @@ def create_toc(html_docs_dir, toc_file="keyword_docs.html", homepage_file="homep
 
     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)}")    
+    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)
@@ -176,79 +256,145 @@ def create_toc(html_docs_dir, toc_file="keyword_docs.html", homepage_file="homep
         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')
+    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:
+    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))
-    
+    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")
+    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_libs = create_docs_for_dir(child_element_path, args.output_dir, os.path.abspath(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_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
+                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):")
+        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):")
+        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)
+        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()