feat(docs): Enhance documentation build process with environment variable configuration

Author: JakubAndrysek

.github/scripts/docs_build_examples.py

@@ -35,17 +35,34 @@
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 
+env_config_keys = [
+    "DOCS_EMBED_PUBLIC_ROOT",
+    "DOCS_EMBED_GITHUB_BASE_URL",
+    "DOCS_EMBED_BINARIES_DIR",
+]
+
+# load environment variables
+env_config = {}
+for key in env_config_keys:
+    value = os.environ.get(key)
+    if value is None:
+        raise EnvironmentError(f"{key} environment variable is not set")
+    env_config[key] = value
+
+
+if env_config.get("DOCS_EMBED_BINARIES_DIR"):
+    DOCS_EMBED_BINARIES_PATH = Path(f"docs/{env_config['DOCS_EMBED_BINARIES_DIR']}")
+
 ARDUINO_ESP32_PATH = os.environ.get("ARDUINO_ESP32_PATH")
 GITHUB_WORKSPACE = os.environ.get("GITHUB_WORKSPACE")
-STORAGE_URL_PREFIX = os.environ.get("STORAGE_URL_PREFIX")
-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"
 elif GITHUB_WORKSPACE and (Path(GITHUB_WORKSPACE) / "tools" / "esp32-arduino-libs").is_dir():
     SDKCONFIG_DIR = Path(GITHUB_WORKSPACE) / "tools" / "esp32-arduino-libs"
 else:
-    SDKCONFIG_DIR = Path("tools/esp32-arduino-libs")
+    raise EnvironmentError("Could not locate esp32-arduino-libs directory. "
+                           "Set ARDUINO_ESP32_PATH or GITHUB_WORKSPACE environment variable.")
 
 KEEP_FILES = [
     "*.merged.bin",
@@ -56,8 +73,6 @@
 ]
 
 SKETCH_UTILS = SCRIPT_DIR / "sketch_utils.sh"
-DOCS_BINARIES_DIR = Path("docs/_static/binaries")
-
 
 def detect_arduino_paths():
     """Get Arduino CLI and user paths from environment variables set by install-arduino-cli.sh
@@ -269,11 +284,11 @@ def cleanup_binaries():
     Removes all files except those matching patterns in KEEP_FILES.
     Also removes empty directories after cleanup.
     """
-    print(f"Cleaning up binaries directory: {DOCS_BINARIES_DIR}")
-    if not DOCS_BINARIES_DIR.exists():
+    print(f"Cleaning up binaries directory: {DOCS_EMBED_BINARIES_PATH}")
+    if not DOCS_EMBED_BINARIES_PATH.exists():
         print("Binaries directory does not exist, nothing to clean")
         return
-    for root, dirs, files in os.walk(DOCS_BINARIES_DIR):
+    for root, dirs, files in os.walk(DOCS_EMBED_BINARIES_PATH):
         for fname in files:
             fpath = Path(root) / fname
             parent = Path(root).name
@@ -292,7 +307,7 @@ def cleanup_binaries():
             else:
                 print(f"Keeping: {fpath}")
     # remove empty dirs
-    for root, dirs, files in os.walk(DOCS_BINARIES_DIR, topdown=False):
+    for root, dirs, files in os.walk(DOCS_EMBED_BINARIES_PATH, topdown=False):
         if not os.listdir(root):
             try:
                 os.rmdir(root)
@@ -356,7 +371,7 @@ def build_example_for_target(sketch_dir, target, relative_path, args):
         bool: True if build succeeded, False otherwise
     """
     print(f"\n > Building example: {relative_path} for target: {target}")
-    output_dir = DOCS_BINARIES_DIR / relative_path / target
+    output_dir = DOCS_EMBED_BINARIES_PATH / relative_path / target
     output_dir.mkdir(parents=True, exist_ok=True)
 
     sdkconfig = SDKCONFIG_DIR / target / 'sdkconfig'
@@ -405,13 +420,13 @@ def build_all_examples(args):
     total_built = 0
     total_failed = 0
 
-    if DOCS_BINARIES_DIR.exists():
-        shutil.rmtree(DOCS_BINARIES_DIR)
-        print(f"Removed existing build directory: {DOCS_BINARIES_DIR}")
+    if DOCS_EMBED_BINARIES_PATH.exists():
+        shutil.rmtree(DOCS_EMBED_BINARIES_PATH)
+        print(f"Removed existing build directory: {DOCS_EMBED_BINARIES_PATH}")
 
     # add gitignore to binaries dir with * for new files
-    DOCS_BINARIES_DIR.mkdir(parents=True, exist_ok=True)
-    gitignore_path = DOCS_BINARIES_DIR / '.gitignore'
+    DOCS_EMBED_BINARIES_PATH.mkdir(parents=True, exist_ok=True)
+    gitignore_path = DOCS_EMBED_BINARIES_PATH / '.gitignore'
     gitignore_path.write_text("*\n")
 
     examples = find_examples_with_upload_binary()
@@ -444,7 +459,7 @@ def build_all_examples(args):
             else:
                 total_failed += 1
 
-        output_sketch_dir = DOCS_BINARIES_DIR / relative_path
+        output_sketch_dir = DOCS_EMBED_BINARIES_PATH / relative_path
         output_sketch_dir.mkdir(parents=True, exist_ok=True)
 
         # copy sketch ci.yml to output dir - parent of target dirs
@@ -455,15 +470,20 @@ def build_all_examples(args):
         if args.generate_launchpad_config:
             print(f"Generating LaunchPad config for {relative_path}/{target}...")
             try:
-                sync = DiagramSync(output_sketch_dir / target)
-                sync.generate_launchpad_config(STORAGE_URL_PREFIX, REPO_URL_PREFIX, True, output_sketch_dir)
+                sync = DiagramSync(output_sketch_dir)
+                sync.generate_launchpad_config(
+                    env_config['DOCS_EMBED_PUBLIC_ROOT'],
+                    env_config['DOCS_EMBED_GITHUB_BASE_URL'],
+                    True,
+                    output_sketch_dir
+                )
             except Exception as e:
                 print(f"WARNING: Failed to generate LaunchPad config for {relative_path}/{target}: {e}")
 
     print('\nBuild summary:')
     print(f"  Successfully built: {total_built}")
     print(f"  Failed builds: {total_failed}")
-    print(f"  Output directory: {DOCS_BINARIES_DIR}")
+    print(f"  Output directory: {DOCS_EMBED_BINARIES_PATH}")
     return total_failed
 
 

.github/workflows/docs_build.yml

@@ -55,7 +55,19 @@ jobs:
           cd ./docs
           PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
 
-          # Build examples using environment variables from install script
+      # Set documentation embedding environment variables
+      - name: Set Documentation Environment Variables
+        run: |
+          # configure env vars for docs_build_examples.py and docs build
+          echo "DOCS_EMBED_GITHUB_BASE_URL=https://github.com/${{ github.repository }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_GITHUB_BRANCH=${{ github.ref_name }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_PUBLIC_ROOT=https://${{ secrets.DOCS_SERVER }}/${{ secrets.DOCS_PATH }}/en/${{ github.ref_name == 'master' && 'latest' || github.ref_name }}/" >> $GITHUB_ENV
+          echo "DOCS_EMBED_BINARIES_DIR=${{ vars.DOCS_EMBED_BINARIES_DIR }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_LAUNCHPAD_URL=${{ vars.DOCS_EMBED_LAUNCHPAD_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_WOKWI_VIEWER_URL=${{ vars.DOCS_EMBED_WOKWI_VIEWER_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_ABOUT_WOKWI_URL=${{ vars.DOCS_EMBED_ABOUT_WOKWI_URL }}" >> $GITHUB_ENV
+
+      # Build examples using environment variables from install script
       - name: Build Examples
         run: |
           PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py --build --diagram --launchpad

.github/workflows/docs_deploy.yml

@@ -63,7 +63,19 @@ jobs:
           cd ./docs
           PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
 
-          # Build examples using environment variables from install script
+      # Set documentation embedding environment variables
+      - name: Set Documentation Environment Variables
+        run: |
+          # configure env vars for docs_build_examples.py and docs deployment
+          echo "DOCS_EMBED_GITHUB_BASE_URL=https://github.com/${{ github.repository }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_GITHUB_BRANCH=${{ github.ref_name }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_PUBLIC_ROOT=https://${{ secrets.DOCS_SERVER }}/${{ secrets.DOCS_PATH }}/en/${{ github.ref_name == 'master' && 'latest' || github.ref_name }}/" >> $GITHUB_ENV
+          echo "DOCS_EMBED_BINARIES_DIR=${{ vars.DOCS_EMBED_BINARIES_DIR }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_LAUNCHPAD_URL=${{ vars.DOCS_EMBED_LAUNCHPAD_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_WOKWI_VIEWER_URL=${{ vars.DOCS_EMBED_WOKWI_VIEWER_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_ABOUT_WOKWI_URL=${{ vars.DOCS_EMBED_ABOUT_WOKWI_URL }}" >> $GITHUB_ENV
+
+      # Build examples using environment variables from install script
       - name: Build Examples
         run: |
           PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py --build --diagram --launchpad

docs/en/conf.py

@@ -33,8 +33,8 @@
 google_analytics_id = "G-F58JM78930"
 
 # Documentation embedding settings
-docs_embed_public_root = "https://docs.espressif.com/projects/arduino-esp32-wokwi-test"
-docs_embed_esp32_relative_root = "../.."
-docs_embed_launchpad_url = "https://espressif.github.io/esp-launchpad/"
-docs_embed_github_base_url = "https://github.com/JakubAndrysek/arduino-esp32"
-docs_embed_github_branch = "docs-embed"
+# docs_embed_public_root = "https://docs.espressif.com/projects/arduino-esp32-wokwi-test"
+# docs_embed_esp32_relative_root = "../.."
+# docs_embed_launchpad_url = "https://espressif.github.io/esp-launchpad/"
+# docs_embed_github_base_url = "https://github.com/JakubAndrysek/arduino-esp32"
+# docs_embed_github_branch = "docs-embed"

libraries/ESP32/examples/GPIO/Blink/Blink.ino

@@ -1,5 +1,5 @@
-#define LED    12
-#define BUTTON 2
+#define LED    4
+#define BUTTON 0
 
 uint8_t stateLED = 0;