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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: robotframework-libtoc
-Version: 1.4.3
+Version: 1.6.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.
@@ -84,11 +84,12 @@ 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`
 
     Examples:
     ```shell
@@ -111,4 +112,3 @@ 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).
-

{robotframework_libtoc-1.4.3 → robotframework_libtoc-1.6.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.
@@ -64,11 +64,12 @@ 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`
 
     Examples:
     ```shell
@@ -90,4 +91,4 @@ 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).

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "robotframework-libtoc"
-version = "1.4.3"
+version = "1.6.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/homepage_template.html

@@ -0,0 +1,31 @@
+<html>
+    <head>
+    <meta charset="utf-8">
+    <style>
+    :root { --bg: white; --text: #333; --text-muted: #666; --kbd-bg: #f3f3f3; --kbd-border: #e0e0e2; }
+    [data-theme=dark] { --bg: #1c2227; --text: #e2e1d7; --text-muted: #a8b2b8; --kbd-bg: #002b36; --kbd-border: #4e4e4e; color-scheme: dark; }
+    body { font-family: system-ui, -apple-system, sans-serif; color: var(--text); background: var(--bg); max-width: 640px; margin: 60px auto; padding: 0 24px; text-align: center; }
+    h1 { font-weight: 600; font-size: 24px; }
+    p { color: var(--text-muted); font-size: 15px; line-height: 1.6; }
+    kbd { background: var(--kbd-bg); border: 1px solid var(--kbd-border); border-radius: 4px; padding: 2px 7px; font-family: monospace; font-size: 12px; }
+    </style>
+    <script>!function(){var t=localStorage.getItem('libtoc-theme')||(window.matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light');document.documentElement.setAttribute('data-theme',t);document.addEventListener('keydown',function(e){if((e.ctrlKey||e.metaKey)&&e.key==='k'){e.preventDefault();window.parent.postMessage('libtoc-open-search','*')}})}()</script>
+    </head>
+    <body>
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
+        viewBox="0 0 202.4325 202.34125" height="120" width="120">
+        <g transform="matrix(1.25,0,0,-1.25,0,202.34125)">
+            <g>
+                <g clip-path="none">
+                    <g transform="translate(52.4477,88.1268)">
+                        <path fill="#00c0b5"
+                            d="m 0,0 c 0,7.6 6.179,13.779 13.77,13.779 7.6,0 13.779,-6.179 13.779,-13.779 0,-2.769 -2.238,-5.007 -4.998,-5.007 -2.761,0 -4.999,2.238 -4.999,5.007 0,2.078 -1.695,3.765 -3.782,3.765 C 11.693,3.765 9.997,2.078 9.997,0 9.997,-2.769 7.76,-5.007 4.999,-5.007 2.238,-5.007 0,-2.769 0,0 m 57.05,-23.153 c 0,-2.771 -2.237,-5.007 -4.998,-5.007 l -46.378,0 c -2.761,0 -4.999,2.236 -4.999,5.007 0,2.769 2.238,5.007 4.999,5.007 l 46.378,0 c 2.761,0 4.998,-2.238 4.998,-5.007 M 35.379,-2.805 c -1.545,2.291 -0.941,5.398 1.35,6.943 l 11.594,7.83 c 2.273,1.58 5.398,0.941 6.943,-1.332 1.545,-2.29 0.941,-5.398 -1.35,-6.943 l -11.594,-7.83 c -0.852,-0.586 -1.829,-0.87 -2.788,-0.87 -1.607,0 -3.187,0.781 -4.155,2.202 m 31.748,-30.786 c 0,-0.945 -0.376,-1.852 -1.045,-2.522 l -8.617,-8.617 c -0.669,-0.668 -1.576,-1.045 -2.523,-1.045 l -52.833,0 c -0.947,0 -1.854,0.377 -2.523,1.045 l -8.617,8.617 c -0.669,0.67 -1.045,1.577 -1.045,2.522 l 0,52.799 c 0,0.947 0.376,1.854 1.045,2.522 l 8.617,8.619 c 0.669,0.668 1.576,1.044 2.523,1.044 l 52.833,0 c 0.947,0 1.854,-0.376 2.523,-1.044 l 8.617,-8.619 c 0.669,-0.668 1.045,-1.575 1.045,-2.522 l 0,-52.799 z m 7.334,61.086 -11.25,11.25 c -1.705,1.705 -4.018,2.663 -6.428,2.663 l -56.523,0 c -2.412,0 -4.725,-0.959 -6.43,-2.665 L -17.412,27.494 c -1.704,-1.705 -2.661,-4.016 -2.661,-6.427 l 0,-56.515 c 0,-2.411 0.958,-4.725 2.663,-6.428 l 11.25,-11.25 c 1.705,-1.705 4.017,-2.662 6.428,-2.662 l 56.515,0 c 2.41,0 4.723,0.957 6.428,2.662 l 11.25,11.25 c 1.705,1.703 2.663,4.017 2.663,6.428 l 0,56.514 c 0,2.412 -0.958,4.724 -2.663,6.429" />
+                    </g>
+                </g>
+            </g>
+        </g>
+    </svg>
+    <h1>Keyword Documentation</h1>
+    <p>Select a library or resource from the sidebar, or press <kbd>Ctrl+K</kbd> to search.</p>
+    </body>
+</html>

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

@@ -1,6 +1,8 @@
 import argparse
 import glob
+import json
 import os
+import re
 import shutil
 import sys
 from datetime import datetime
@@ -15,7 +17,7 @@ class LibdocException(Exception):
         self.broken_file = broken_file
 
 
-def toc(links, timestamp, home_page_path, template_file=""):
+def toc(links, timestamp, home_page_path, template_file="", search_index=None):
     """
     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.
@@ -25,27 +27,34 @@ def toc(links, timestamp, home_page_path, template_file=""):
     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("}", "}}")
+    result = html_template.replace("{}", home_page_path, 1)
+    result = result.replace("{}", links, 1)
+    if timestamp:
+        result = result.replace("{}", timestamp, 1)
+    else:
+        result = result.replace("Created: {}", "", 1)
 
-    # and convert the formatting brackets back
-    html_with_escaped_braces = html_with_escaped_braces.replace("{{}}", "{}")
+    # inject search index data (done after format() to avoid brace escaping issues)
+    if search_index is not None:
+        search_json = json.dumps(search_index, ensure_ascii=False)
+        search_json = search_json.replace("</script>", r"<\/script>")
+        result = result.replace("SEARCH_INDEX_DATA", search_json)
+    else:
+        result = result.replace("SEARCH_INDEX_DATA", "[]")
 
-    return html_with_escaped_braces.format(home_page_path, links, timestamp)
+    return result
 
 
-def homepage(timestamp, template_file=""):
+def homepage(template_file=""):
     """
-    Returns a HTML source code for a landing page, based on the template and includig the provided `timestamp`.
+    Returns a HTML source code for a landing page, based on the template.
     """
     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)
+        return f.read()
 
 
 def read_config(config_file):
@@ -96,6 +105,139 @@ def read_config(config_file):
     }
 
 
+def extract_libdoc_data(html_file_path):
+    """
+    Extracts the libdoc JSON data from a generated libdoc HTML file.
+    The libdoc variable is embedded as a JSON object in a script tag.
+    """
+    with open(html_file_path, encoding="utf-8") as f:
+        content = f.read()
+    for line in content.split("\n"):
+        stripped = line.strip()
+        if stripped.startswith("libdoc") and '"specversion"' in stripped:
+            json_start = stripped.index("{")
+            json_str = stripped[json_start:]
+            try:
+                return json.loads(json_str)
+            except json.JSONDecodeError:
+                print(f"Warning: Failed to parse libdoc JSON (for global searches) in file {html_file_path}")
+    return None
+
+
+def build_search_index(src_dir, base_dir, homepage_file):
+    """
+    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_file:
+                file_path = os.path.join(dirpath, file_name)
+                data = extract_libdoc_data(file_path)
+                if data:
+                    rel_path = os.path.relpath(file_path, base_dir)
+                    rel_path = rel_path.replace("\\", "/")
+                    keywords = []
+                    for kw in data.get("keywords", []):
+                        args_list = []
+                        for a in kw.get("args", []):
+                            if isinstance(a, str):
+                                args_list.append(a)
+                            elif isinstance(a, dict):
+                                args_list.append(
+                                    a.get("repr", a.get("name", ""))
+                                )
+                        keywords.append(
+                            {
+                                "name": kw.get("name", ""),
+                                "args": ", ".join(args_list),
+                                "shortdoc": kw.get("shortdoc", ""),
+                                "tags": kw.get("tags", []),
+                            }
+                        )
+                    doc_text = re.sub(r"<[^>]+>", "", data.get("doc", ""))
+                    # file_name without .html extension for file searching
+                    name_without_ext = os.path.splitext(file_name)[0]
+                    index.append(
+                        {
+                            "name": data.get("name", ""),
+                            "fileName": name_without_ext,
+                            "path": rel_path,
+                            "doc": doc_text,
+                            "type": data.get("type", ""),
+                            "keywords": keywords,
+                        }
+                    )
+    return index
+
+
+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 (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.
+    - Opens all external links (http/https/ftp/protocol-relative) in a new tab via
+      a click event listener, so dynamically-rendered links are handled correctly.
+    - Forwards Ctrl+K / Cmd+K keypresses to the parent frame to open the libtoc search.
+    """
+    libtoc_script = (
+        '\n<script>!function(){var t=localStorage.getItem("libtoc-theme")'
+        '||(window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light");'
+        'document.documentElement.setAttribute("data-theme",t);'
+        'document.addEventListener("DOMContentLoaded",function(){'
+        'document.documentElement.setAttribute("data-theme",t)});'
+        'document.addEventListener("click",function(e){'
+        'var el=e.target.closest("a");'
+        'if(el){var h=el.getAttribute("href");'
+        'if(h&&/^(https?:|ftp:\\/\\/|\\/\\/)/i.test(h)){'
+        'e.preventDefault();'
+        'window.open(h,"_blank","noopener,noreferrer")}}});'
+        'document.addEventListener("keydown",function(e){'
+        'if((e.ctrlKey||e.metaKey)&&e.key==="k"){'
+        'e.preventDefault();'
+        'window.parent.postMessage("libtoc-open-search","*")}})'
+        '}()</script>\n'
+    )
+    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()
+                # Insert before </head> - uses DOMContentLoaded + setTimeout
+                # to override libdoc's own theme initialization
+                if "libtoc-theme" not in content:
+                    content = content.replace("</head>", libtoc_script + "</head>", 1)
+                    with open(file_path, "w", encoding="utf-8") as f:
+                        f.write(content)
+
+
 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.
@@ -236,6 +378,7 @@ def create_toc(
     homepage_file="homepage.html",
     toc_template="",
     homepage_template="",
+    no_timestamp=False,
 ):
     """
     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.
@@ -259,10 +402,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")
+    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))
     with open(homepage_path, "w", encoding="utf8") as f:
-        f.write(homepage(current_date_time, homepage_template))
+        f.write(homepage(homepage_template))
+
+    # build search index from generated docs
+    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, homepage_file)
 
     # create TOC
     toc_file_path = os.path.join(html_docs_dir, toc_file)
@@ -273,6 +426,7 @@ def create_toc(
                 current_date_time,
                 os.path.relpath(homepage_path, os.path.abspath(html_docs_dir)),
                 toc_template,
+                search_index,
             )
         )
 
@@ -306,6 +460,12 @@ 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",
@@ -389,6 +549,7 @@ def main():
             args.toc_file,
             toc_template=args.toc_template,
             homepage_template=args.homepage_template,
+            no_timestamp=args.no_timestamp,
         )
     else:
         print("No docs were created!")