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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: robotframework-libtoc
-Version: 1.5.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
@@ -21,7 +21,7 @@ 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 (or multiple folders) 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.
@@ -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)
@@ -84,11 +84,13 @@ pip install robotframework-libtoc
 - 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_dirs` parameter is mandatory, it takes any number of paths. Other params are optional:
     - `-d, --output_dir`
+    - `-P, --pythonpath`
     - `--config_file`
     - `--toc_file`
     - `--toc_template`
     - `--homepage_template`
-    - `-P, --pythonpath`
+    - `--no_timestamp`
+    - `--tree-label`
 
     Examples:
     ```shell
@@ -97,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 +115,13 @@ There are two ways to extend the list of paths where the libraries are searched
 
 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.5.0 → robotframework_libtoc-1.7.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 (or multiple folders) 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.
@@ -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)
@@ -64,11 +64,13 @@ pip install robotframework-libtoc
 - 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_dirs` parameter is mandatory, it takes any number of paths. Other params are optional:
     - `-d, --output_dir`
+    - `-P, --pythonpath`
     - `--config_file`
     - `--toc_file`
     - `--toc_template`
     - `--homepage_template`
-    - `-P, --pythonpath`
+    - `--no_timestamp`
+    - `--tree-label`
 
     Examples:
     ```shell
@@ -77,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,3 +94,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.5.0 → robotframework_libtoc-1.7.0}/pyproject.toml

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

@@ -29,7 +29,10 @@ def toc(links, timestamp, home_page_path, template_file="", search_index=None):
 
     result = html_template.replace("{}", home_page_path, 1)
     result = result.replace("{}", links, 1)
-    result = result.replace("{}", timestamp, 1)
+    if timestamp:
+        result = result.replace("{}", timestamp, 1)
+    else:
+        result = result.replace("Created: {}", "", 1)
 
     # inject search index data (done after format() to avoid brace escaping issues)
     if search_index is not None:
@@ -121,16 +124,16 @@ def extract_libdoc_data(html_file_path):
     return None
 
 
-def build_search_index(src_dir, base_dir):
+def build_search_index(src_dir, base_dir, homepage_file):
     """
-    Builds a search index from all libdoc HTML files in src_dir.
+    Builds a search index from all libdoc HTML files in src_dir (except ``homepage_file``).
     Returns a list of library/resource entries with their keywords.
     """
     index = []
     for dirpath, dirnames, filenames in os.walk(src_dir):
         dirnames.sort()
         for file_name in sorted(filenames):
-            if file_name.endswith(".html") and file_name != "homepage.html":
+            if file_name.endswith(".html") and file_name != homepage_file:
                 file_path = os.path.join(dirpath, file_name)
                 data = extract_libdoc_data(file_path)
                 if data:
@@ -170,9 +173,31 @@ def build_search_index(src_dir, base_dir):
     return index
 
 
-def inject_libtoc_script(src_dir):
+def strip_libdoc_timestamps(src_dir, homepage_file):
+    """
+    Removes the 'generated' timestamp from the libdoc JSON data embedded in each
+    libdoc HTML file in src_dir (except ``homepage_file``), replacing it with an empty string.
+    """
+    for dirpath, dirnames, filenames in os.walk(src_dir):
+        dirnames.sort()
+        for file_name in sorted(filenames):
+            if file_name.endswith(".html") and file_name != homepage_file:
+                file_path = os.path.join(dirpath, file_name)
+                with open(file_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                new_content = re.sub(
+                    r'"generated":\s*"[^"]*"',
+                    '"generated": ""',
+                    content,
+                )
+                if new_content != content:
+                    with open(file_path, "w", encoding="utf-8") as f:
+                        f.write(new_content)
+
+
+def inject_libtoc_script(src_dir, homepage_file):
     """
-    Injects a small <script> into each libdoc HTML file in src_dir that:
+    Injects a small <script> into each libdoc HTML file in src_dir (except ``homepage_file``) that:
     - Reads the theme from localStorage and applies data-theme on <html> so the
       page respects the libtoc theme choice even when file:// cross-origin prevents
       parent frame DOM access.
@@ -201,7 +226,7 @@ def inject_libtoc_script(src_dir):
     for dirpath, dirnames, filenames in os.walk(src_dir):
         dirnames.sort()
         for file_name in sorted(filenames):
-            if file_name.endswith(".html") and file_name != "homepage.html":
+            if file_name.endswith(".html") and file_name != homepage_file:
                 file_path = os.path.join(dirpath, file_name)
                 with open(file_path, "r", encoding="utf-8") as f:
                     content = f.read()
@@ -213,18 +238,30 @@ def inject_libtoc_script(src_dir):
                         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">
@@ -234,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:
@@ -353,6 +391,8 @@ def create_toc(
     homepage_file="homepage.html",
     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.
@@ -376,16 +416,20 @@ def create_toc(
 
     # 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))
+    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), folder_and_file_labels=folder_labels)
     with open(homepage_path, "w", encoding="utf8") as f:
         f.write(homepage(homepage_template))
 
     # build search index from generated docs
-    search_index = build_search_index(src_subdir, os.path.abspath(html_docs_dir))
+    search_index = build_search_index(src_subdir, os.path.abspath(html_docs_dir), homepage_file)
+
+    # strip timestamps from libdoc HTML files if requested
+    if no_timestamp:
+        strip_libdoc_timestamps(src_subdir, homepage_file)
 
     # inject libtoc script into all libdoc HTML files
-    inject_libtoc_script(src_subdir)
+    inject_libtoc_script(src_subdir, homepage_file)
 
     # create TOC
     toc_file_path = os.path.join(html_docs_dir, toc_file)
@@ -430,18 +474,38 @@ def main():
         default="",
         help="Custom HTML template for the homepage file",
     )
+    parser.add_argument(
+        "--no_timestamp",
+        action="store_true",
+        default=False,
+        help="Do not include timestamps in the generated TOC and libdoc HTML files",
+    )
     parser.add_argument(
         "-P",
         "--pythonpath",
         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)
@@ -513,6 +577,8 @@ def main():
             args.toc_file,
             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!")