feat(docs): enhance example build script and CI workflow with diagram generation and updated requirements

Author: JakubAndrysek

.github/scripts/docs_build_examples.py

@@ -8,6 +8,7 @@
 
 import argparse
 from argparse import RawDescriptionHelpFormatter
+from esp_docs.generic_extensions.docs_embed.tool.wokwi_tool import DiagramSync
 import json
 import os
 import shutil
@@ -20,6 +21,9 @@
 # Determine SDKCONFIG_DIR like the shell script
 ARDUINO_ESP32_PATH = os.environ.get("ARDUINO_ESP32_PATH")
 GITHUB_WORKSPACE = os.environ.get("GITHUB_WORKSPACE")
+DOCS_DEPLOY_URL_BASE = os.environ.get("DOCS_PROD_URL_BASE")
+REPO_URL_PREFIX = os.environ.get("REPO_URL_PREFIX")
+
 
 if ARDUINO_ESP32_PATH and (Path(ARDUINO_ESP32_PATH) / "tools" / "esp32-arduino-libs").is_dir():
     SDKCONFIG_DIR = Path(ARDUINO_ESP32_PATH) / "tools" / "esp32-arduino-libs"
@@ -31,10 +35,15 @@
 # Wrapper functions to call sketch_utils.sh
 SKETCH_UTILS = SCRIPT_DIR / "sketch_utils.sh"
 
-KEEP_FILES = ["*.merged.bin", "ci.json"]
+KEEP_FILES = [
+    "*.merged.bin",
+    "ci.json",
+    "launchpad.toml",
+    "diagram*.json",
+]
 DOCS_BINARIES_DIR = Path("docs/_static/binaries")
 GENERATE_DIAGRAMS = False
-LAUNCHPAD_STORAGE_URL = ""
+GENERATE_LAUNCHPAD_CONFIG = False
 
 
 def run_cmd(cmd, check=True, capture_output=False, text=True):
@@ -117,8 +126,9 @@ def parse_args(argv):
     )
     p.add_argument(
         "-l",
-        dest="launchpad_storage_url",
-        help="LaunchPad storage URL to include in generated config",
+        dest="generate_launchpad_config",
+        action="store_true",
+        help="Generate LaunchPad config with configured storage URL",
     )
     return p.parse_args(argv)
 
@@ -233,42 +243,18 @@ def build_example_for_target(sketch_dir, target, relative_path, args):
             shutil.copy(ci_json, output_dir / 'ci.json')
         if GENERATE_DIAGRAMS:
             print(f"Generating diagram for {relative_path} ({target})...")
-            rc = run_cmd(
-                [
-                    "docs-embed",
-                    "--path",
-                    str(output_dir),
-                    "diagram-from-ci",
-                    "--platform",
-                    target,
-                    "--override",
-                ],
-                check=False,
-            )
-            if rc.returncode == 0:
-                print("Diagram generated successfully for {relative_path} ({target})")
-            else:
-                print("WARNING: Failed to generate diagram for {relative_path} ({target})")
-        if LAUNCHPAD_STORAGE_URL:
+            try:
+                sync = DiagramSync(output_dir)
+                sync.generate_diagram_from_ci(target)
+            except Exception as e:
+                print(f"WARNING: Failed to generate diagram for {relative_path} ({target}): {e}")
+        if GENERATE_LAUNCHPAD_CONFIG:
             print(f"Generating LaunchPad config for {relative_path} ({target})...")
-            rc = run_cmd(
-                [
-                    "docs-embed",
-                    "--path",
-                    str(output_dir),
-                    "launchpad-config",
-                    LAUNCHPAD_STORAGE_URL,
-                    "--repo-url-prefix",
-                    "https://github.com/espressif/arduino-esp32/tree/master",
-                    "--override",
-                ],
-                check=False,
-            )
-            if rc.returncode == 0:
-                print("LaunchPad config generated successfully for {relative_path} ({target})")
-            else:
-                print("WARNING: Failed to generate LaunchPad config for {relative_path} ({target})")
-        return True
+            try:
+                sync = DiagramSync(output_dir)
+                sync.generate_launchpad_config(DOCS_DEPLOY_URL_BASE, REPO_URL_PREFIX)
+            except Exception as e:
+                print(f"WARNING: Failed to generate LaunchPad config for {relative_path} ({target}): {e}")
     else:
         print(f"ERROR: Failed to build {relative_path} for {target}")
         return False
@@ -320,14 +306,14 @@ def build_all_examples(args):
 
 
 def main(argv):
-    global GENERATE_DIAGRAMS, LAUNCHPAD_STORAGE_URL
+    global GENERATE_DIAGRAMS, GENERATE_LAUNCHPAD_CONFIG
     args = parse_args(argv)
     if args.cleanup:
         cleanup_binaries()
         return
     validate_prerequisites(args)
     GENERATE_DIAGRAMS = args.generate_diagrams
-    LAUNCHPAD_STORAGE_URL = args.launchpad_storage_url or ""
+    GENERATE_LAUNCHPAD_CONFIG = args.generate_launchpad_config
     DOCS_BINARIES_DIR.mkdir(parents=True, exist_ok=True)
     result = build_all_examples(args)
     if result == 0:

.github/workflows/docs_build.yml

@@ -35,16 +35,6 @@ jobs:
           cache: "pip"
           python-version: "3.10"
 
-      - name: Build
-        run: |
-          sudo apt update
-          sudo apt install python3-pip python3-setuptools
-          # GitHub CI installs pip3 and setuptools outside the path.
-          # Update the path to include them and run.
-          cd ./docs
-          PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
-          PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en
-
       - name: Build Examples
         run: |
           source .github/scripts/install-arduino-cli.sh
@@ -55,6 +45,16 @@ jobs:
         run: |
           python3 .github/scripts/docs_build_examples.py -c
 
+      - name: Build
+        run: |
+          sudo apt update
+          sudo apt install python3-pip python3-setuptools
+          # GitHub CI installs pip3 and setuptools outside the path.
+          # Update the path to include them and run.
+          cd ./docs
+          PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
+          PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en
+
       - name: Archive Docs
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:

docs/requirements.txt

@@ -1,7 +1,7 @@
-sphinx==4.5.0
+sphinx
 esp-docs @ git+https://github.com/JakubAndrysek/esp-docs.git@extensions/wokwi_embed
-sphinx-copybutton==0.5.0
-sphinx-tabs==3.2.0
-numpydoc==1.5.0
-standard-imghdr==3.13.0
-Sphinx-Substitution-Extensions==2022.2.16
+sphinx-copybutton
+sphinx-tabs
+numpydoc
+standard-imghdr
+Sphinx-Substitution-Extensions