robotframework-libtoc 1.6.0__tar.gz → 1.7.0__tar.gz

{robotframework_libtoc-1.6.0 → robotframework_libtoc-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: robotframework-libtoc
-Version: 1.6.0
+Version: 1.7.0
 Summary: Docs and TOC generator for Robot Framework resources and libs
 Home-page: https://github.com/amochin/robotframework-libtoc
 License: Apache-2.0
@@ -40,7 +40,7 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 - It looks for the **config files** named `.libtoc` which contain items you would like to create docs for:
     1. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming))
     2. RF libraries, installed or available in PYTHONPATH using the provided fully qualified name
-        > Librariy import params (if necessary) like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
+        > Library import params (if necessary) 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
     3. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming)) inside Python packages, loaded from the PYTHONPATH
         > See more about bundling RF resources in Python packages in [RF User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#taking-resource-files-into-use)
@@ -90,6 +90,7 @@ pip install robotframework-libtoc
     - `--toc_template`
     - `--homepage_template`
     - `--no_timestamp`
+    - `--tree-label`
 
     Examples:
     ```shell
@@ -98,6 +99,7 @@ pip install robotframework-libtoc
     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
+    libtoc --tree-label "my_folder=My Display Name" --tree-label "my_lib=My Lib Label" example_resources
     ```
 
 - Open the created file, e.g. `docs/keyword_docs.html`
@@ -112,3 +114,14 @@ There are two ways to extend the list of paths where the libraries are searched
 2. Set the **PYTHONPATH** environment variable
 
 See more in [Robot Framework User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath).
+
+## How to customize TOC tree item labels
+By default the TOC navigation tree uses the original folder, file and library names.  
+Use `--tree-label KEY=VALUE` to replace any folder, library or file name (without extension) with a custom display label — without affecting the actual file paths.   
+
+The option can be repeated any number of times:
+```shell
+libtoc --tree-label "sut_x=SUT X (Production)" --tree-label "common=Common Keywords" example_resources
+```
+> - Only the visible label in the tree is changed. Folder structure and file paths remain untouched.   
+> - If the item name is found multiple times in the TOC, all occurrences would be replaced.

{robotframework_libtoc-1.6.0 → robotframework_libtoc-1.7.0}/README.md

@@ -20,7 +20,7 @@ in the intranet or uploaded as CI artifact - so everybody can easily access the
 - It looks for the **config files** named `.libtoc` which contain items you would like to create docs for:
     1. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming))
     2. RF libraries, installed or available in PYTHONPATH using the provided fully qualified name
-        > Librariy import params (if necessary) like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
+        > Library import params (if necessary) 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
     3. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming)) inside Python packages, loaded from the PYTHONPATH
         > See more about bundling RF resources in Python packages in [RF User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#taking-resource-files-into-use)
@@ -70,6 +70,7 @@ pip install robotframework-libtoc
     - `--toc_template`
     - `--homepage_template`
     - `--no_timestamp`
+    - `--tree-label`
 
     Examples:
     ```shell
@@ -78,6 +79,7 @@ pip install robotframework-libtoc
     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
+    libtoc --tree-label "my_folder=My Display Name" --tree-label "my_lib=My Lib Label" example_resources
     ```
 
 - Open the created file, e.g. `docs/keyword_docs.html`
@@ -91,4 +93,15 @@ There are two ways to extend the list of paths where the libraries are searched
 1. Using the `--pythonpath` option
 2. Set the **PYTHONPATH** environment variable
 
-See more in [Robot Framework User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath).
+See more in [Robot Framework User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath).
+
+## How to customize TOC tree item labels
+By default the TOC navigation tree uses the original folder, file and library names.  
+Use `--tree-label KEY=VALUE` to replace any folder, library or file name (without extension) with a custom display label — without affecting the actual file paths.   
+
+The option can be repeated any number of times:
+```shell
+libtoc --tree-label "sut_x=SUT X (Production)" --tree-label "common=Common Keywords" example_resources
+```
+> - Only the visible label in the tree is changed. Folder structure and file paths remain untouched.   
+> - If the item name is found multiple times in the TOC, all occurrences would be replaced.

{robotframework_libtoc-1.6.0 → robotframework_libtoc-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "robotframework-libtoc"
-version = "1.6.0"
+version = "1.7.0"
 description = "Docs and TOC generator for Robot Framework resources and libs"
 authors = ["Andre Mochinin"]
 license = "Apache-2.0"

{robotframework_libtoc-1.6.0 → robotframework_libtoc-1.7.0}/robotframework_libtoc/libtoc.py

@@ -238,18 +238,30 @@ def inject_libtoc_script(src_dir, homepage_file):
                         f.write(content)
 
 
-def add_files_from_folder(folder, base_dir_path, root=True):
+def add_files_from_folder(folder, base_dir_path, root=True, folder_and_file_labels=None):
     """
     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.
     """
+
+    def get_label_for_file_or_folder(item_name, labels):
+        if item_name in labels:
+            item_display_name = labels[item_name]
+            print(f">> Modified label of tree item: '{item_name}' -> '{item_display_name}'")
+        else:
+            item_display_name = item_name
+        return item_display_name
+
+    if folder_and_file_labels is None:
+        folder_and_file_labels = {}
     result_str = ""
     if not root:  # means we're in the root - no collapsible need in this case
+        folder_display_name = get_label_for_file_or_folder(os.path.basename(folder), folder_and_file_labels)
         result_str += """<button class="collapsible">{}</button>
         """.format(
-            os.path.basename(folder)
+            folder_display_name
         )
 
         result_str += """<div class="collapsible_content">
@@ -259,14 +271,15 @@ def add_files_from_folder(folder, base_dir_path, root=True):
         item_path = os.path.abspath(os.path.join(folder, item))
         if item.endswith(".html"):
             name_without_ext = os.path.splitext(item)[0]
+            display_name = get_label_for_file_or_folder(name_without_ext, folder_and_file_labels)
             result_str += """<a class="link_not_selected" href="{}" target="targetFrame">{}</a>
             """.format(
-                os.path.relpath(item_path, base_dir_path), name_without_ext
+                os.path.relpath(item_path, base_dir_path), display_name
             )
         else:
             if os.path.isdir(item_path):
                 result_str += add_files_from_folder(
-                    item_path, base_dir_path, root=False
+                    item_path, base_dir_path, root=False, folder_and_file_labels=folder_and_file_labels
                 )
 
     if not root:
@@ -379,6 +392,7 @@ def create_toc(
     toc_template="",
     homepage_template="",
     no_timestamp=False,
+    folder_labels=None,
 ):
     """
     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.
@@ -403,7 +417,7 @@ def create_toc(
     # create homepage in "src"
     homepage_path = os.path.join(src_subdir, homepage_file)
     current_date_time = "" if no_timestamp else datetime.now().strftime("%d.%m.%Y %H:%M:%S")
-    doc_files_links = add_files_from_folder(src_subdir, os.path.abspath(html_docs_dir))
+    doc_files_links = add_files_from_folder(src_subdir, os.path.abspath(html_docs_dir), folder_and_file_labels=folder_labels)
     with open(homepage_path, "w", encoding="utf8") as f:
         f.write(homepage(homepage_template))
 
@@ -472,12 +486,26 @@ def main():
         default="",
         help="Additional locations where to search for libraries and resources similarly as when running tests",
     )
+    parser.add_argument(
+        "--tree-label",
+        dest="folder_labels",
+        action="append",
+        metavar="KEY=VALUE",
+        default=[],
+        help="Replace folder, file or lib name KEY with VALUE in the TOC tree. Can be specified multiple times, e.g. --tree-label 'SUT X=My Project'",
+    )
 
     args = parser.parse_args()
 
     if args.pythonpath:
         sys.path.insert(0, args.pythonpath)
 
+    folder_labels = {}
+    for kv in args.folder_labels:
+        if "=" in kv:
+            key, _, value = kv.partition("=")
+            folder_labels[key] = value
+
     if os.path.isdir(args.output_dir):
         print(f"Output dir already exists, deleting it: {args.output_dir}")
         shutil.rmtree(args.output_dir)
@@ -550,6 +578,7 @@ def main():
             toc_template=args.toc_template,
             homepage_template=args.homepage_template,
             no_timestamp=args.no_timestamp,
+            folder_labels=folder_labels,
         )
     else:
         print("No docs were created!")