feat(docs): enhance security in command execution and improve error handling in scripts

Author: JakubAndrysek

.github/scripts/docs_build_examples.py

@@ -70,23 +70,41 @@
 SKETCH_UTILS = SCRIPT_DIR / "sketch_utils.sh"
 
 
-def run_cmd(cmd, check=True, capture_output=False, text=True):
-    """Execute a shell command with error handling."""
+def run_sketch_utils(subcommand, *args, check=True, capture_output=False, text=True):
+    """Execute sketch_utils.sh with a controlled subcommand.
+
+    Security:
+      * Uses a fixed script path (SKETCH_UTILS)
+      * Only allows known subcommands
+      * Always calls subprocess.run with shell=False and a list of arguments
+    """
+    allowed_subcommands = {"check_requirements", "install_libs", "build"}
+    if subcommand not in allowed_subcommands:
+        raise ValueError(f"Unsupported sketch_utils.sh subcommand: {subcommand}")
+
+    cmd = [str(SKETCH_UTILS), subcommand]
+    for arg in args:
+        if not isinstance(arg, (str, os.PathLike)):
+            raise ValueError(f"Invalid argument type for sketch_utils.sh: {type(arg)!r}")
+        cmd.append(str(arg))
+
     try:
         return subprocess.run(
-            cmd, check=check, capture_output=capture_output, text=text
+            cmd,
+            check=check,
+            capture_output=capture_output,
+            text=text,
+            shell=False,  # explicit for static analyzers
         )
     except subprocess.CalledProcessError as e:
-        # CalledProcessError is raised only when check=True and the command exits non-zero
         print(f"ERROR: Command failed: {' '.join(cmd)}")
         print(f"Exit code: {e.returncode}")
-        if hasattr(e, "stdout") and e.stdout:
+        if e.stdout:
             print("--- stdout ---")
             print(e.stdout)
-        if hasattr(e, "stderr") and e.stderr:
+        if e.stderr:
             print("--- stderr ---")
             print(e.stderr)
-        # Exit the whole script with the same return code to mimic shell behavior
         sys.exit(e.returncode)
     except FileNotFoundError:
         print(f"ERROR: Command not found: {cmd[0]}")
@@ -103,24 +121,27 @@ def check_requirements(sketch_dir, sdkconfig_path):
     Returns:
         bool: True if requirements are met, False otherwise
     """
-    cmd = [str(SKETCH_UTILS), "check_requirements", sketch_dir, str(sdkconfig_path)]
     try:
-        res = run_cmd(cmd, check=False, capture_output=True)
+        res = run_sketch_utils(
+            "check_requirements",
+            sketch_dir,
+            str(sdkconfig_path),
+            check=False,
+            capture_output=True,
+        )
         return res.returncode == 0
     except Exception:
         return False
 
 
 def install_libs(*args):
     """Install Arduino libraries using sketch_utils.sh"""
-    cmd = [str(SKETCH_UTILS), "install_libs"] + list(args)
-    return run_cmd(cmd, check=False)
+    return run_sketch_utils("install_libs", *args, check=False)
 
 
 def build_sketch(args_list):
     """Build a sketch using sketch_utils.sh"""
-    cmd = [str(SKETCH_UTILS), "build"] + args_list
-    return run_cmd(cmd, check=False)
+    return run_sketch_utils("build", *args_list, check=False)
 
 
 def parse_args(argv):
@@ -260,8 +281,8 @@ def cleanup_binaries():
         if not os.listdir(root):
             try:
                 os.rmdir(root)
-            except Exception:
-                pass
+            except Exception as e:
+                print(f"WARNING: Failed to remove empty directory {root}: {e}")
     print("Cleanup completed")
 
 
@@ -284,7 +305,8 @@ def find_examples_with_upload_binary():
                 data = yaml.safe_load(ci_yml.read_text())
                 if "upload-binary" in data and data["upload-binary"]:
                     res.append(str(ino))
-            except Exception:
+            except Exception as e:
+                print(f"WARNING: Failed to parse ci.yml for {ci_yml}: {e}")
                 continue
     return res
 

docs/en/conf.py

@@ -31,10 +31,3 @@
 
 # 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"

docs/en/contributing.rst

@@ -109,6 +109,93 @@ Also:
     const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled
     const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password
 
+
+Examples
+********
+
+All libraries in the Arduino ESP32 core has its own examples. You can found them in the ``libraries/<library_name>/examples/`` folder.
+
+The purpose of these examples is to demonstrate how to use the library features and provide a starting point for users.
+
+If you want to show the example in the documentation, you have two options:
+1. link just the source code file in the documentation using the ``literalinclude`` directive:
+
+.. code-block:: rst
+
+    .. literalinclude:: ../../../libraries/<library_name>/examples/<example_name>/<example_name>.ino
+      :language: arduino
+
+2. Source code with Wokwi simulation embedded in the documentation using the ``wokwi-example`` directive:
+
+.. code-block:: rst
+
+    .. wokwi-example:: libraries/<library_name>/examples/<example_name>/<example_name>.ino
+
+To enable compiling the example in the CI system, you need to add a ``ci.yml`` file in the same folder as the sketch.
+The ``ci.yml`` file is used to specify some configurations for the CI system, like required configurations, supported targets, and more.
+You can enable compilation of the example by adding targets under the ``upload-binary`` directive in the ``ci.yml`` file.
+
+Here is an example of a ``ci.yml`` file that enables compilation for ESP32 and ESP32-S3 targets.
+This configuration adds default diagrams for Wokwi simulations with just dev boards.
+
+.. code-block:: yaml
+
+    upload-binary:
+      targets:
+        - esp32
+        - esp32s3
+
+If you want to add custom diagrams for Wokwi simulations, you can add the ``diagram.<target>.json`` file in the same folder as the sketch.
+The ``<target>`` is the target name (e.g., ``esp32``, ``esp32s3``, etc.). You can create the diagram using ``docs-embed`` tool installed together with documentation building tools.
+
+To create the diagram, run the ``docs-embed init-diagram --platforms esp32`` command in the sketch folder.
+You can edit them and before you run the documentation build command, you have to convert the diagram config to the ``ci.yml`` file format by running:
+
+.. code-block:: bash
+
+    docs-embed ci-from-diagram
+    # OR
+    docs-embed ci-from-diagram --override
+
+There is also opposite command to generate diagram from ``ci.yml`` file:
+
+.. code-block:: bash
+
+    docs-embed diagram-from-ci
+
+
+The documentation building tools is working only with `ci.yml` files, so `diagram.<target>.json` files are just for configuration using GUI tool.
+
+Please keep in mind that the ``ci.yml`` does not store the chip and its position on the diagram, just the components and their connections (to save space).
+The chip is added automatically and positioned vertically in the center of the diagram (same as the default behavior of the `docs-embed init-diagram` command).
+
+To run the documentation build command locally and in the CI system, you need to add those environment variables:
+
+* ``DOCS_EMBED_ABOUT_WOKWI_URL``: URL to the info about Wokwi (default: ``https://docs.espressif.com/projects/arduino-esp32/en/latest/third_party/wokwi.html``)
+* ``DOCS_EMBED_BINARIES_DIR``: Path to the folder where the pre-compiled binaries are stored (default: ``_static/binaries``)
+* ``DOCS_EMBED_LAUNCHPAD_URL``: URL to the launchpad page (default: ``https://espressif.github.io/esp-launchpad/``)
+* ``DOCS_EMBED_WOKWI_VIEWER_URL``: URL to the Wokwi iframe viewer (default: ``https://wokwi.com/experimental/viewer``)
+
+
+CI/CD
+*****
+
+This repository uses GitHub Actions for Continuous Integration and Continuous Deployment (CI/CD).
+If you forked the repository, you can enable them under the `Actions` tab in your forked repository.
+
+To enable building the documentation, you need to set up additional secrets and environment variables in your forked repository.
+
+Secrets
+^^^^^^^^^^^^
+* ``DOCS_SERVER``: The server where the documentation will be deployed
+* ``DOCS_PATH``: The path where the documentation will be deployed on the server
+
+
+Variables
+^^^^^^^^^
+
+They are described above in the `Examples` section.
+
 Testing
 *******