ci(deploy): generate index with template

StaticRocket · StaticRocket · commit 2c9bc7e5b62f · 2025-07-10T17:14:36.000-05:00
We already pull in jinja2 as a dependency of sphinx. Might as well put
it to use here to make this process a little more bulletproof.

Signed-off-by: Randolph Sapp &lt;rs@ti.com&gt;
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -12,8 +12,18 @@ jobs:
   agregate:
     name: Agregate build artifacts
     runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/texasinstruments/processor-sdk-doc:latest
+      options: --entrypoint /bin/bash
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Add directory to safe dir overrides
+        run: |
+          git config --global --add safe.directory "$PWD"
+
       - name: Download all artifacts
         uses: actions/download-artifact@v4
         with:
@@ -23,36 +33,7 @@ jobs:
           run-id: ${{ github.event.workflow_run.id }}
 
       - name: Generate root index
-        run: |
-          cat << EOF > build/index.html
-          <!DOCTYPE html>
-          <html lang="en">
-            <head>
-              <meta charset="utf-8">
-              <title>PSDK Documentation Landing Page</title>
-            </head>
-            <body>
-              <main>
-                <h1>PSDK Documentation Landing Page</h1>
-                <ul>
-          EOF
-
-          for path in build/*/; do
-            root_index=$(find "$path" -name index.html -print -quit)
-            if [ -n "$root_index" ]; then
-              text=$(basename "$path")
-              relative_path=$(realpath "$root_index" --relative-to=build)
-              printf '        <li><a href="%s">%s</a></li>\n' \
-                "$relative_path" "$text" >> build/index.html
-            fi
-          done
-
-          cat << EOF >> build/index.html
-                </ul>
-              </main>
-            </body>
-          </html>
-          EOF
+        run: ./bin/root_index.py
 
       - name: Upload static files as single artifact
         uses: actions/upload-pages-artifact@v3
diff --git a/bin/root_index.html b/bin/root_index.html
@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>PSDK Documentation Landing Page</title>
+  </head>
+  <body>
+    <main>
+      <h1>PSDK Documentation Landing Page</h1>
+      <p>
+        The following documentation is currently available:
+      </p>
+      <ul>
+        {% for path in path_list -%}
+        <li>
+          <a href="{{ path }}">{{ path.parts[0] }}</a>
+        </li>
+        {%- endfor %}
+      </ul>
+    </main>
+  </body>
+</html>
diff --git a/bin/root_index.py b/bin/root_index.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+
+"""Tool to find and make a index of doc root index files
+
+SPDX-License-Identifier: MIT
+Copyright (C) 2025 Texas Instruments Incorporated - https://www.ti.com
+"""
+
+from pathlib import Path
+import logging
+from jinja2 import Environment, FileSystemLoader
+
+BUILD_PATH = Path("build/")
+TEMPLATE_PATH = Path(__file__).parent
+
+logger = logging.getLogger(__name__)
+
+
+def get_root_index(path):
+    """Get the root index from a list of candidates
+
+    :param path: Pathlib path to search in
+    """
+    candidates = [x for x in path.glob("**/index.html") if x.is_file()]
+    if not candidates:
+        return None
+
+    sorted_paths = sorted(candidates, key=lambda x: len(x.parts))
+    return sorted_paths[0]
+
+
+def get_index_list():
+    """Get the list of index files to use from the build directory"""
+    index_list = []
+    for path in BUILD_PATH.glob("*/"):
+        root = get_root_index(path)
+        if root:
+            logging.info("Found index: %s", root)
+            root = root.relative_to(BUILD_PATH)
+            logging.info("Updating path to: %s", root)
+            index_list.append(root)
+    return sorted(index_list)
+
+
+def generate_root_index(index_list):
+    """Make the root index file
+
+    :param index_list: List of pathlib paths to indexes
+    """
+    root_index_path = BUILD_PATH.joinpath("index.html")
+    logging.info("Loading jinja env")
+    env = Environment(loader=FileSystemLoader(TEMPLATE_PATH))
+    template = env.get_template("root_index.html")
+    logging.info("Using template: %s", template.name)
+    output = template.render(path_list=index_list)
+    logging.info("Writing output to: %s", root_index_path)
+    with root_index_path.open("w", encoding="utf-8") as f:
+        f.write(output)
+
+
+def main():
+    """Main processing loop"""
+    logging.basicConfig(level=logging.INFO)
+    index_list = get_index_list()
+    generate_root_index(index_list)
+
+
+if __name__ == "__main__":
+    main()
