feat(docs): Add documentation build examples script and update CI workflows

JakubAndrysek · JakubAndrysek · commit 787163bd14a3 · 2025-10-24T15:16:55.000+02:00
diff --git a/.github/scripts/docs_build_examples.py b/.github/scripts/docs_build_examples.py
diff --git a/.github/scripts/sketch_utils.sh b/.github/scripts/sketch_utils.sh
@@ -54,6 +54,8 @@ function check_requirements { # check_requirements <sketchdir> <sdkconfig_path>
 }
 
 function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [extra-options]
+    local first_only=false
+
     while [ -n "$1" ]; do
         case "$1" in
         -ai )
@@ -92,6 +94,36 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
             shift
             debug_level="DebugLevel=$1"
             ;;
+        -b )
+            shift
+            custom_build_dir=$1
+            ;;
+        --first-only )
+            first_only=true
+            ;;
+        -h )
+            echo "Usage: build_sketch [options]"
+            echo ""
+            echo "Build an Arduino sketch for ESP32 targets."
+            echo ""
+            echo "Required options:"
+            echo "  -ai <path>          Arduino IDE path"
+            echo "  -au <path>          Arduino user path"
+            echo "  -s <path>           Sketch directory containing .ino file and ci.yml"
+            echo "  -t <target>         Target chip (esp32, esp32s2, esp32c3, esp32s3, esp32c6, esp32h2, esp32p4, esp32c5)"
+            echo "                      Required unless -fqbn is specified"
+            echo ""
+            echo "Optional options:"
+            echo "  -fqbn <fqbn>        Fully qualified board name (alternative to -t)"
+            echo "  -o <options>        Board options (PSRAM, USBMode, etc.) [default: chip-specific]"
+            echo "  -i <index>          Chunk index for parallel builds [default: none]"
+            echo "  -l <file>           Log compilation output to JSON file [default: none]"
+            echo "  -d <level>          Debug level (DebugLevel=...) [default: none]"
+            echo "  -b <path>           Custom build directory [default: \$ARDUINO_BUILD_DIR or \$HOME/.arduino/tests/\$target/\$sketchname/build.tmp]"
+            echo "  --first-only        Build only the first FQBN from ci.yml configurations [default: false]"
+            echo "  -h                  Show this help message"
+            exit 0
+            ;;
         * )
             break
             ;;
@@ -128,7 +160,15 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
 
             len=$(yq eval ".fqbn.${target} | length" "$sketchdir"/ci.yml 2>/dev/null || echo 0)
             if [ "$len" -gt 0 ]; then
-                fqbn=$(yq eval ".fqbn.${target} | sort | @json" "$sketchdir"/ci.yml)
+                if [ "$first_only" = true ]; then
+                    # Get only the first FQBN from the array (original order)
+                    fqbn=$(yq eval ".fqbn.${target} | .[0]" "$sketchdir"/ci.yml 2>/dev/null)
+                    fqbn="[\"$fqbn\"]"
+                    len=1
+                else
+                    # Build all FQBNs
+                    fqbn=$(yq eval ".fqbn.${target} | sort | @json" "$sketchdir"/ci.yml)
+                fi
             fi
         fi
 
@@ -219,12 +259,14 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
     fi
 
     # The directory that will hold all the artifacts (the build directory) is
-    # provided through:
-    #  1. An env variable called ARDUINO_BUILD_DIR.
-    #  2. Created at the sketch level as "build" in the case of a single
-    #     configuration test.
-    #  3. Created at the sketch level as "buildX" where X is the number
-    #     of configuration built in case of a multiconfiguration test.
+    # determined by the following priority:
+    #  1. Custom build directory via -b flag:
+    #     - If path contains "docs/_static/binaries", use as exact path (for docs builds)
+    #     - Otherwise, append target name to custom directory
+    #  2. ARDUINO_BUILD_DIR environment variable (if set)
+    #  3. Default: $HOME/.arduino/tests/$target/$sketchname/build.tmp
+    #
+    # For multiple configurations, subsequent builds use .1, .2, etc. suffixes
 
     sketchname=$(basename "$sketchdir")
     local has_requirements
@@ -253,22 +295,34 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
     fi
 
     ARDUINO_CACHE_DIR="$HOME/.arduino/cache.tmp"
-    if [ -n "$ARDUINO_BUILD_DIR" ]; then
-        build_dir="$ARDUINO_BUILD_DIR"
-    elif [ "$len" -eq 1 ]; then
-        # build_dir="$sketchdir/build"
-        build_dir="$HOME/.arduino/tests/$target/$sketchname/build.tmp"
+
+    # Determine base build directory
+    if [ -n "$custom_build_dir" ]; then
+        # If custom_build_dir contains docs/_static/binaries, use it as exact path
+        if [[ "$custom_build_dir" == *"docs/_static/binaries"* ]]; then
+            build_dir_base="$custom_build_dir"
+        else
+            build_dir_base="$custom_build_dir/$target"
+        fi
+    elif [ -n "$ARDUINO_BUILD_DIR" ]; then
+        build_dir_base="$ARDUINO_BUILD_DIR"
+    else
+        build_dir_base="$HOME/.arduino/tests/$target/$sketchname/build.tmp"
     fi
 
     output_file="$HOME/.arduino/cli_compile_output.txt"
     sizes_file="$GITHUB_WORKSPACE/cli_compile_$chunk_index.json"
 
     mkdir -p "$ARDUINO_CACHE_DIR"
     for i in $(seq 0 $((len - 1))); do
-        if [ "$len" -ne 1 ]; then
-            # build_dir="$sketchdir/build$i"
-            build_dir="$HOME/.arduino/tests/$target/$sketchname/build$i.tmp"
+        # Calculate build directory for this configuration
+        if [ "$i" -eq 0 ]; then
+            build_dir="$build_dir_base"
+        else
+            build_dir="${build_dir_base}.${i}"
         fi
+
+        # Prepare build directory
         rm -rf "$build_dir"
         mkdir -p "$build_dir"
 
diff --git a/.github/workflows/docs_build.yml b/.github/workflows/docs_build.yml
@@ -5,6 +5,7 @@ on:
     branches:
       - master
       - release/v2.x
+      - docs-embed
     paths:
       - "docs/**"
       - ".github/workflows/docs_build.yml"
@@ -34,18 +35,38 @@ jobs:
           cache: "pip"
           python-version: "3.10"
 
-      - name: Build
+          # Install Arduino CLI and set environment variables
+      - name: Install Arduino CLI
+        run: |
+          source .github/scripts/install-arduino-cli.sh
+          echo "ARDUINO_IDE_PATH=$ARDUINO_IDE_PATH" >> $GITHUB_ENV
+          echo "ARDUINO_USR_PATH=$ARDUINO_USR_PATH" >> $GITHUB_ENV
+
+      # Install Python dependencies needed for docs_build_examples.py
+      - name: Install Python Dependencies
         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
+
+          # 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
+
+      - name: Cleanup Binaries
+        run: |
+          PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py -c
+
+
+      - name: Build
+        run: |
+          cd ./docs
           PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en
 
       - name: Archive Docs
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: docs
-          path: docs
+          path: docs
diff --git a/.github/workflows/docs_deploy.yml b/.github/workflows/docs_deploy.yml
@@ -1,6 +1,7 @@
 name: Documentation Build and Production Deploy CI
 
 on:
+  workflow_dispatch:
   workflow_run:
     workflows: ["ESP32 Arduino Release"]
     types:
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -35,6 +35,7 @@
     "sphinx_tabs.tabs",
     "sphinx_substitution_extensions",  # For allowing substitutions inside code blocks
     "esp_docs.esp_extensions.dummy_build_system",
+    "esp_docs.generic_extensions.docs_embed",
 ]
 
 # ESP32_DOCS = [
diff --git a/docs/en/api/gpio.rst b/docs/en/api/gpio.rst
@@ -141,25 +141,7 @@ Example Code
 GPIO Input and Output Modes
 ***************************
 
-.. code-block:: arduino
-
-  #define LED    12
-  #define BUTTON 2
-
-  uint8_t stateLED = 0;
-
-    void setup() {
-        pinMode(LED, OUTPUT);
-        pinMode(BUTTON,INPUT_PULLUP);
-    }
-
-    void loop() {
-
-       if(!digitalRead(BUTTON)){
-         stateLED = stateLED^1;
-        digitalWrite(LED,stateLED);
-      }
-    }
+.. wokwi-example:: libraries/ESP32/examples/GPIO/Blink
 
 GPIO Interrupt
 **************
diff --git a/docs/en/conf.py b/docs/en/conf.py
@@ -31,3 +31,10 @@
 
 # Tracking ID for Google Analytics
 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"
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,9 @@
-sphinx==4.5.0
-esp-docs>=1.4.0
+sphinx~=7.1.2
+
+esp-docs @ git+https://github.com/JakubAndrysek/esp-docs.git@extensions/wokwi_embed
+
 sphinx-copybutton==0.5.0
-sphinx-tabs==3.2.0
+sphinx-tabs==3.4.7
 numpydoc==1.5.0
 standard-imghdr==3.13.0
 Sphinx-Substitution-Extensions==2022.2.16
diff --git a/libraries/ESP32/examples/GPIO/Blink/Blink.ino b/libraries/ESP32/examples/GPIO/Blink/Blink.ino
@@ -0,0 +1,16 @@
+#define LED    12
+#define BUTTON 2
+
+uint8_t stateLED = 0;
+
+void setup() {
+  pinMode(LED, OUTPUT);
+  pinMode(BUTTON, INPUT_PULLUP);
+}
+
+void loop() {
+  if (!digitalRead(BUTTON)) {
+    stateLED = !stateLED;
+    digitalWrite(LED, stateLED);
+  }
+}
diff --git a/libraries/ESP32/examples/GPIO/Blink/ci.yml b/libraries/ESP32/examples/GPIO/Blink/ci.yml
@@ -0,0 +1,78 @@
+upload-binary:
+  targets:
+    - esp32
+    - esp32s3
+  diagram:
+    esp32:
+      parts:
+        - type: wokwi-pushbutton
+          id: btn1
+          top: 140.6
+          left: 144
+          attrs:
+            color: green
+        - type: wokwi-led
+          id: led1
+          top: 66
+          left: 131.4
+          rotate: 90
+          attrs:
+            color: red
+      connections:
+        - - btn1:1.l
+          - esp:0
+          - blue
+          - - h-19.2
+            - v-19.2
+        - - btn1:2.r
+          - esp:GND.1
+          - black
+          - - h19.4
+            - v48.2
+            - h-240
+            - v-67.2
+        - - esp:GND.2
+          - led1:C
+          - black
+          - - h33.64
+            - v114.8
+        - - esp:4
+          - led1:A
+          - green
+          - - h0
+    esp32s3:
+      parts:
+        - type: wokwi-pushbutton
+          id: btn1
+          top: 140.6
+          left: 115.2
+          attrs:
+            color: green
+        - type: wokwi-led
+          id: led1
+          top: 66.4
+          left: -56.2
+          rotate: 270
+          attrs:
+            color: red
+            flip: ""
+      connections:
+        - - btn1:1.l
+          - esp:0
+          - blue
+          - - h-19.2
+            - v0
+            - h-4.57
+        - - btn1:2.r
+          - esp:GND.3
+          - green
+          - - h19.4
+            - v48.38
+        - - esp:4
+          - led1:A
+          - green
+          - - h0
+        - - esp:GND.1
+          - led1:C
+          - black
+          - - h0

Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,7 @@`
`35`	`35`	`"sphinx_tabs.tabs",`
`36`	`36`	`"sphinx_substitution_extensions", # For allowing substitutions inside code blocks`
`37`	`37`	`"esp_docs.esp_extensions.dummy_build_system",`
	`38`	`+ "esp_docs.generic_extensions.docs_embed",`
`38`	`39`	`]`
`39`	`40`
`40`	`41`	`# ESP32_DOCS = [`