Merge pull request #239 from espressif/docs/update_docs

docs: add missing documentation for wokwi
espressif · Nov 7, 2023 · 220f0ad · 220f0ad
2 parents 9c38392 + 34aea7a
commit 220f0ad
Show file tree

Hide file tree

Showing 8 changed files with 44 additions and 22 deletions.
diff --git a/.github/workflows/test-python.yml b/.github/workflows/test-python.yml
@@ -4,6 +4,7 @@ on:
   pull_request:
     paths:
       - '**.py'
+      - '!docs/**'
   push:
     branches: [ main ]
 

diff --git a/README.md b/README.md
@@ -14,6 +14,7 @@ All packages are published to PyPI. Please install them via `pip`.
 [![pytest-embedded-idf](https://img.shields.io/pypi/v/pytest-embedded-idf?color=green&label=pytest-embedded-idf)](https://pypi.org/project/pytest-embedded-idf/)
 [![pytest-embedded-qemu](https://img.shields.io/pypi/v/pytest-embedded-qemu?color=green&label=pytest-embedded-qemu)](https://pypi.org/project/pytest-embedded-qemu/)
 [![pytest-embedded-arduino](https://img.shields.io/pypi/v/pytest-embedded-arduino?color=green&label=pytest-embedded-arduino)](https://pypi.org/project/pytest-embedded-arduino/)
+[![pytest-embedded-wokwi](https://img.shields.io/pypi/v/pytest-embedded-wokwi?color=green&label=pytest-embedded-wokwi)](https://pypi.org/project/pytest-embedded-wokwi/)
 
 ## Quick Example
 
@@ -59,7 +60,7 @@ The `print` line is also duplicated to console output.
 
 ## Extra Services
 
-You can activate more services with `pytest --embedded-services service[, service]` to enable extra fixtures and functionalities.
+You can activate more services with `pytest --embedded-services service[,service]` to enable extra fixtures and functionalities.
 These services are provided by several optional dependencies. You can install them via `pip` as well.
 
 Available services:
@@ -70,6 +71,7 @@ Available services:
 - `jtag`: openocd/gdb utilities
 - `qemu`: running test cases on QEMU instead of the real target.
 - `arduino`: auto-detect more app info with [arduino](https://github.com/arduino/Arduino) specific rules, auto-flash the binary into the target.
+- `wokwi`: running test cases with [Wokwi](https://wokwi.com/) instead of the real target.
 
 ## Resources
 

diff --git a/docs/api.rst b/docs/api.rst
@@ -121,3 +121,21 @@ pytest-embedded-qemu
    :members:
    :undoc-members:
    :show-inheritance:
+
+pytest-embedded-wokwi
+---------------------
+
+.. automodule:: pytest_embedded_wokwi.wokwi_cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_wokwi.dut
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_wokwi.idf
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
@@ -33,7 +33,3 @@
 html_logo = '_static/espressif-logo.svg'
 html_static_path = ['_static']
 html_theme = 'sphinx_rtd_theme'
-
-# mermaid 10.0.0 change the CDN path
-# temp workaround until sphinxcontrib-mermaid fixed it
-mermaid_version = '9.4.0'
diff --git a/docs/expecting.md b/docs/expecting.md
@@ -81,7 +81,7 @@ def test_expect_from_eof_current_buffer(dut):
 .. note::
 
     The pexpect process would only read from the process into the buffer when running expecting functions.
-    If you're expecting `pexpect.EOF` as the first statement, it would return an empty byte string
+    If you're expecting ``pexpect.EOF`` as the first statement, it would return an empty byte string
 
     .. code-block:: python
 

diff --git a/docs/key_concepts.md b/docs/key_concepts.md
@@ -14,7 +14,7 @@ Each test case would initialize a few fixtures. The most important fixtures are:
 ```{eval-rst}
 .. note::
 
-    You may redirect any output to the `msg_queue` fixture by `contextlib.redirect_stdout`.
+    You may redirect any output to the ``msg_queue`` fixture by ``contextlib.redirect_stdout``.
 
     .. code-block:: python
 
@@ -70,7 +70,7 @@ def test_serial_tcp(dut):
 
 ## Services
 
-You can activate more services with `pytest --embedded-services service[, service]` to enable extra fixtures and functionalities. These services are provided by several optional dependencies. You can install them via `pip` as well.
+You can activate more services with `pytest --embedded-services service[,service]` to enable extra fixtures and functionalities. These services are provided by several optional dependencies. You can install them via `pip` as well.
 
 Available services:
 
@@ -80,6 +80,7 @@ Available services:
 - `jtag`: openocd/gdb utilities.
 - `qemu`: running test cases on QEMU instead of the real target.
 - `arduino`: auto-detect more app info with [arduino](https://github.com/arduino/Arduino) specific rules, auto-flash the binary into the target.
+- `wokwi`: running test cases with [Wokwi](https://wokwi.com/) instead of the real target.
 
 ## Multi DUTs
 

diff --git a/docs/services.md b/docs/services.md
@@ -8,7 +8,21 @@ Please refer to instructions under the "fixtures defined from pytest_embedded.pl
 
 Please refer to the instructions under the "embedded" or "embedded-[SERVICE]" groups of the output of `pytest --help`.
 
-## Services
+## Dependency Graph
+
+```{mermaid}
+graph LR
+    pytest_embedded --> pytest_embedded_serial
+    pytest_embedded -->|pytest_embedded_serial_esp is an optional dependency| pytest_embedded_idf
+    pytest_embedded -->|pytest_embedded_idf is an optional dependency| pytest_embedded_qemu
+    pytest_embedded -->|pytest_embedded_serial is an optional dependency| pytest_embedded_arduino
+    pytest_embedded -->|pytest_embedded_idf is an optional dependency| pytest_embedded_wokwi
+
+    pytest_embedded_serial --> pytest_embedded_serial_esp
+    pytest_embedded_serial --> pytest_embedded_jtag
+```
+
+## Supported Services
 
 Activate a service would enable a set of fixtures or add some extra functionalities to a few fixtures.
 
@@ -30,15 +44,5 @@ Activate a service would enable a set of fixtures or add some extra functionalit
 ```{include} ../pytest-embedded-arduino/README.md
 ```
 
-## Dependency Graph
-
-```{mermaid}
-graph LR
-    pytest_embedded --> pytest_embedded_serial
-    pytest_embedded -->|pytest_embedded_serial_esp is an optional dependency| pytest_embedded_idf
-    pytest_embedded -->|pytest_embedded_idf is an optional dependency| pytest_embedded_qemu
-    pytest_embedded -->|pytest_embedded_serial is an optional dependency| pytest_embedded_arduino
-
-    pytest_embedded_serial --> pytest_embedded_serial_esp
-    pytest_embedded_serial --> pytest_embedded_jtag
+```{include} ../pytest-embedded-wokwi/README.md
 ```
diff --git a/pytest-embedded-wokwi/README.md b/pytest-embedded-wokwi/README.md
@@ -6,7 +6,7 @@ Wokwi supports most ESP32 targets, including: esp32, esp32s2, esp32s3, esp32c3,
 
 Running the tests with Wokwi requires an internet connection. Your firmware is uploaded to the Wokwi server for the duration of the simulation, but it is not saved on the server. On-premises Wokwi installations are available for enterprise customers.
 
-## Wokwi CLI installation
+#### Wokwi CLI installation
 
 The Wokwi plugin uses the [Wokwi CLI](https://github.com/wokwi/wokwi-cli) to interact with the wokwi simulation server. You can download the precompiled CLI binaries from the [releases page](https://github.com/wokwi/wokwi-cli/releases). Alternatively, on Linux or Mac OS, you can install the CLI using the following command:
 
@@ -20,7 +20,7 @@ And on Windows:
 iwr https://wokwi.com/ci/install.ps1 -useb | iex
 ```
 
-## API Tokens
+#### Wokwi API Tokens
 
 Before using this plugin, you need to create a free Wokwi account and [generate an API key](https://wokwi.com/dashboard/ci). You can then set the `WOKWI_CLI_TOKEN` environment variable to the API key.