docs #22
docs #22
Conversation
…able configuration
…directive; modify AnalogRead example pin usage
…I configurations for consistency
… esp_extensions fix(examples): Modify Blink example to increase LED blink duration to 500ms
👋 Hello JakubAndrysek, we appreciate your contribution to this project! 📘 Please review the project's Contributions Guide for key guidelines on code, documentation, testing, and more. 🖊️ Please also make sure you have read and signed the Contributor License Agreement for this project. Click to see more instructions ...
Review and merge process you can expect ...
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| """Execute a shell command with error handling.""" | ||
| try: | ||
| return subprocess.run( | ||
| cmd, check=check, capture_output=capture_output, text=text |
Check failure
Code scanning / CodeQL
Uncontrolled command line Critical
| if not os.listdir(root): | ||
| try: | ||
| os.rmdir(root) | ||
| except Exception: |
Check notice
Code scanning / CodeQL
Insufficient Logging Low
| data = yaml.safe_load(ci_yml.read_text()) | ||
| if "upload-binary" in data and data["upload-binary"]: | ||
| res.append(str(ino)) | ||
| except Exception: |
Check notice
Code scanning / CodeQL
Insufficient Logging Low
Memory usage test (comparing PR against master branch)The table below shows the summary of memory usage change (decrease - increase) in bytes and percentage for each target.
Click to expand the detailed deltas report [usage change in BYTES]
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Test Results 83 files 83 suites 37m 43s ⏱️ For more details on these failures and errors, see this check. Results for commit 576b303. ♻️ This comment has been updated with latest results. |
JakubAndrysek
force-pushed
the
docs-embed
branch
from
9bb4740 to
8eeab63
Compare
There was a problem hiding this comment.
Pull request overview
This PR adds Wokwi simulation integration to documentation examples, enabling interactive hardware simulations embedded directly in the documentation pages. The changes include CI/CD automation for building example binaries, Wokwi diagram configurations, and updates to the documentation build system.
Key Changes
- Added Wokwi simulation support through new
upload-binaryCI configurations and diagram definitions for multiple examples (GPIO, Timer, ADC, I2C, RMT) - Created
docs_build_examples.pyscript to automate example compilation and binary preparation for documentation - Updated documentation build workflows to compile examples and generate Wokwi diagrams during CI/CD
Reviewed changes
Copilot reviewed 22 out of 23 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| libraries/Wire/examples/LiquidCrystal_I2C/ci.yml | New CI config for I2C LCD example with ESP32 target and Wokwi diagram |
| libraries/Wire/examples/LiquidCrystal_I2C/LiquidCrystal_I2C.ino | New example demonstrating I2C LCD control |
| libraries/ESP32/examples/Timer/WatchdogTimer/ci.yml | New CI config enabling watchdog timer example build |
| libraries/ESP32/examples/Timer/RepeatTimer/ci.yml | New CI config enabling repeat timer example build |
| libraries/ESP32/examples/RMT/RMTWrite_RGB_LED/ci.yml | New CI config with Wokwi diagrams for ESP32 and ESP32H2 |
| libraries/ESP32/examples/RMT/RMTWrite_RGB_LED/RMTWrite_RGB_LED.ino | Updated RGB LED pin from 21 to 4 to match Wokwi diagram |
| libraries/ESP32/examples/GPIO/GPIOInterrupt/ci.yml | New CI config with button wiring diagrams for multiple targets |
| libraries/ESP32/examples/GPIO/GPIOInterrupt/GPIOInterrupt.ino | Updated button pins to 0 and 4, added serial output for better debugging |
| libraries/ESP32/examples/GPIO/Blink/ci.yml | New CI config with LED and button wiring diagrams |
| libraries/ESP32/examples/GPIO/Blink/Blink.ino | New blink example with button control |
| libraries/ESP32/examples/AnalogRead/ci.yml | New CI config with potentiometer wiring diagram |
| docs/requirements.txt | Updated Sphinx and dependencies, added esp-docs from feature branch |
| docs/en/contributing.rst | Added comprehensive documentation for examples, Wokwi integration, and CI/CD setup |
| docs/en/api/timer.rst | Replaced literalinclude with wokwi-example directive for interactive examples |
| docs/en/api/i2c.rst | Added LiquidCrystal_I2C example section with Wokwi integration |
| docs/en/api/gpio.rst | Replaced code blocks with wokwi-example directives for GPIO examples |
| docs/en/api/adc.rst | Replaced literalinclude with wokwi-example directive |
| docs/conf_common.py | Added docs_embed extension for Wokwi integration |
| .gitignore | Added pattern to exclude Wokwi diagram files except in tests |
| .github/workflows/docs_deploy.yml | Added Arduino CLI setup, example building, and environment configuration for deployments |
| .github/workflows/docs_build.yml | Added Arduino CLI setup and example building to docs build workflow |
| .github/scripts/sketch_utils.sh | Enhanced build script with custom build directory support and first-only FQBN option |
| .github/scripts/docs_build_examples.py | New Python script to build documentation examples with diagram and LaunchPad config generation |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| branches: | ||
| - release/v2.x | ||
| - master | ||
| - docs-embed |
There was a problem hiding this comment.
[nitpick] The branch name docs-embed has been added to the workflow triggers. This appears to be a development/feature branch. Before merging to production, consider whether this branch should remain in the trigger list or if it should be removed to keep the workflow running only on the main branches (master, release/v2.x).
| - docs-embed |
| branches: | ||
| - master | ||
| - release/v2.x | ||
| - docs-embed |
There was a problem hiding this comment.
[nitpick] The branch name docs-embed has been added to the workflow triggers. This appears to be a development/feature branch. Before merging to production, consider whether this branch should remain in the trigger list or if it should be removed to keep the workflow running only on the main branches (master, release/v2.x).
| - docs-embed |
docs/en/contributing.rst
Outdated
| 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: |
There was a problem hiding this comment.
Typo: "You can edit them and before you run" should be "You can edit them, and before you run" (missing comma) or better "You can edit them. Before you run" (use a period to separate the sentences more clearly).
| 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: | |
| You can edit them. Before you run the documentation build command, you have to convert the diagram config to the ``ci.yml`` file format by running: |
docs/en/contributing.rst
Outdated
| # OR | ||
| docs-embed ci-from-diagram --override | ||
| There is also opposite command to generate diagram from ``ci.yml`` file: |
There was a problem hiding this comment.
Typo: "There is also opposite command" should be "There is also an opposite command" (missing article "an").
| There is also opposite command to generate diagram from ``ci.yml`` file: | |
| There is also an opposite command to generate diagram from ``ci.yml`` file: |
docs/en/contributing.rst
Outdated
| 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. |
There was a problem hiding this comment.
Typo: "using GUI tool" should be "using a GUI tool" (missing article "a").
| The documentation building tools is working only with `ci.yml` files, so `diagram.<target>.json` files are just for configuration using GUI tool. | |
| The documentation building tools is working only with `ci.yml` files, so `diagram.<target>.json` files are just for configuration using a GUI tool. |
| deploy-prod-docs: | ||
| name: Deploy Documentation on Production | ||
| if: github.repository == 'espressif/arduino-esp32' | ||
| # if: github.repository == 'espressif/arduino-esp32' |
There was a problem hiding this comment.
The repository check has been commented out, which means this workflow will now run on forks. This could be intentional for testing, but in production, this should typically remain uncommented to prevent unnecessary workflow runs on forks. Consider whether this change is intentional or if it should be reverted before merging.
| # if: github.repository == 'espressif/arduino-esp32' | |
| if: github.repository == 'espressif/arduino-esp32' |
docs/en/contributing.rst
Outdated
|
|
||
| .. code-block:: rst | ||
| .. wokwi-example:: libraries/<library_name>/examples/<example_name>/<example_name>.ino |
There was a problem hiding this comment.
The documentation example shows the wokwi-example directive with the .ino file included (<example_name>.ino), but the actual usage throughout this PR (in gpio.rst, adc.rst, i2c.rst) uses just the directory path without the .ino file. This inconsistency should be corrected - either update this documentation to match the actual usage, or update all the actual usages to match this documentation.
| .. wokwi-example:: libraries/<library_name>/examples/<example_name>/<example_name>.ino | |
| .. wokwi-example:: libraries/<library_name>/examples/<example_name> |
| LiquidCrystal_I2C | ||
| ^^^^^^^^^^^^^^^^^ | ||
|
|
||
| This example demonstrates how to use the `LiquidCrystal_I2C`_ library to control an LCD display via I2C. |
There was a problem hiding this comment.
The LiquidCrystal_I2C reference is used but never defined. You need to add a link definition at the end of the file, for example:
.. _LiquidCrystal_I2C: https://github.com/johnrickman/LiquidCrystal_I2COtherwise, the Sphinx build will produce a warning about an undefined reference.
docs/en/contributing.rst
Outdated
| Examples | ||
| ******** | ||
|
|
||
| All libraries in the Arduino ESP32 core has its own examples. You can found them in the ``libraries/<library_name>/examples/`` folder. |
There was a problem hiding this comment.
Grammatical error: "All libraries in the Arduino ESP32 core has" should be "All libraries in the Arduino ESP32 core have" (subject-verb agreement).
| All libraries in the Arduino ESP32 core has its own examples. You can found them in the ``libraries/<library_name>/examples/`` folder. | |
| All libraries in the Arduino ESP32 core have their own examples. You can find them in the ``libraries/<library_name>/examples/`` folder. |
| esp-docs>=1.4.0 | ||
| sphinx~=7.1.2 | ||
|
|
||
| esp-docs @ git+https://github.com/JakubAndrysek/esp-docs.git@extensions/wokwi_embed |
There was a problem hiding this comment.
Using a Git URL with a specific branch for esp-docs can cause issues:
- This references a non-default branch (
extensions/wokwi_embed) which may be unstable or temporary - Using
@with a branch name (not a commit hash or tag) means builds are not reproducible - the branch content can change - This could break documentation builds if the branch is deleted or rebased
Consider using a specific commit hash instead of a branch name for reproducibility, or better yet, use a released version once this feature is merged into a stable release.
| esp-docs @ git+https://github.com/JakubAndrysek/esp-docs.git@extensions/wokwi_embed | |
| esp-docs @ git+https://github.com/JakubAndrysek/esp-docs.git@<commit-hash> |
…andling in scripts
JakubAndrysek
force-pushed
the
docs-embed
branch
from
8eeab63 to
06debb5
Compare
… execution in docs_build_examples.py
By completing this PR sufficiently, you help us to review this Pull Request quicker and also help improve the quality of Release Notes
Checklist
This entire section above can be deleted if all items are checked.
Description of Change
Please describe your proposed Pull Request and it's impact.
Test Scenarios
Please describe on what Hardware and Software combinations you have tested this Pull Request and how.
(eg. I have tested my Pull Request on Arduino-esp32 core v2.0.2 with ESP32 and ESP32-S2 Board with this scenario)
Related links
Please provide links to related issue, PRs etc.
(eg. Closes #number of issue)