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

Author: JakubAndrysek

.github/scripts/docs_build_examples.py

@@ -72,9 +72,25 @@
 
 def run_cmd(cmd, check=True, capture_output=False, text=True):
     """Execute a shell command with error handling."""
+    # Security: Ensure cmd is always a list to prevent command injection
+    if isinstance(cmd, str):
+        raise ValueError("cmd must be a list, not a string, to prevent command injection")
+    if not isinstance(cmd, list) or not cmd:
+        raise ValueError("cmd must be a non-empty list")
+    # Validate all elements are strings
+    if not all(isinstance(arg, str) for arg in cmd):
+        raise ValueError("All cmd arguments must be strings")
+    # Reject control characters that could alter argv parsing at the OS level
+    for arg in cmd:
+        if any(ch in arg for ch in ("\n", "\r", "\0")):
+            raise ValueError("Command arguments must not contain control characters")
     try:
         return subprocess.run(
-            cmd, check=check, capture_output=capture_output, text=text
+            cmd,
+            check=check,
+            capture_output=capture_output,
+            text=text,
+            shell=False,
         )
     except subprocess.CalledProcessError as e:
         # CalledProcessError is raised only when check=True and the command exits non-zero
@@ -260,8 +276,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 +300,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
 *******