Merge pull request #288 from espressif/docs/improve_latest_feature

Author: hfudev

.pre-commit-config.yaml

@@ -8,22 +8,38 @@ exclude: |
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: mixed-line-ending
-        args: [ '-f=lf' ]
+        args: ["-f=lf"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.3.0'
+    rev: "v0.4.3"
     hooks:
       - id: ruff
-        args: ['--fix', '--preview']
+        args: ["--fix", "--preview"]
       - id: ruff-format
-        args: ['--preview']
+        args: ["--preview"]
+
+  # documentation
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: v0.9.1
+    hooks:
+      - id: sphinx-lint
+        args: [--enable=default-role]
+  - repo: https://github.com/dzhu/rstfmt
+    rev: v0.0.14
+    hooks:
+      - id: rstfmt
+        args: ["-w", "-1"]
+        files: \.rst$
+
+  # git commit
   - repo: https://github.com/espressif/conventional-precommit-linter
-    rev: v1.6.0
+    rev: v1.8.0
     hooks:
       - id: conventional-precommit-linter
         stages: [commit-msg]
-        args: ['--types=chore,change,ci,docs,feat,fix,refactor,remove,revert,bump']
+        args:
+          ["--types=chore,change,ci,docs,feat,fix,refactor,remove,revert,bump"]

README.md

@@ -6,8 +6,6 @@ A pytest plugin that has multiple services available for various functionalities
 
 ## Installation
 
-All packages are published to PyPI. Please install them via `pip`.
-
 [![pytest-embedded](https://img.shields.io/pypi/v/pytest-embedded?color=green&label=pytest-embedded)](https://pypi.org/project/pytest-embedded/)
 [![pytest-embedded-serial](https://img.shields.io/pypi/v/pytest-embedded-serial?color=green&label=pytest-embedded-serial)](https://pypi.org/project/pytest-embedded-serial/)
 [![pytest-embedded-serial-esp](https://img.shields.io/pypi/v/pytest-embedded-serial-esp?color=green&label=pytest-embedded-serial-esp)](https://pypi.org/project/pytest-embedded-serial-esp/)
@@ -16,9 +14,17 @@ All packages are published to PyPI. Please install them via `pip`.
 [![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
+Packages under this repo mainly use semantic versioning. Sometimes a bug fix version may contain some non-breaking new features as well.
+
+It is recommended to use `~=1.0` to get rid of breaking changes, and use the latest new features. For example,
+
+```shell
+pip install -U pytest-embedded~=1.0
+```
+
+## Quickstart
 
-- `pip install pytest-embedded`
+- `pip install -U pytest-embedded~=1.0`
 - Create a file `test_basic.py`
 
 ```python
@@ -60,8 +66,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.
-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:
 
@@ -77,7 +82,3 @@ Available services:
 
 - Documentation is hosted at [https://docs.espressif.com/projects/pytest-embedded/en/latest/](https://docs.espressif.com/projects/pytest-embedded/en/latest/)
 - More examples under [examples](https://github.com/espressif/pytest-embedded/tree/main/examples)
-
-## Versioning
-
-Packages under this repo mainly use semantic versioning. Sometimes a bug fix version may contain some non-breaking new features as well. It is recommended to use `pytest-embdded~=1.0` to get rid of breaking changes, and use the latest new features.

docs/api.rst

@@ -0,0 +1,13 @@
+#########################
+ pytest-embedded-arduino
+#########################
+
+.. automodule:: pytest_embedded_arduino.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_arduino.serial
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apis/pytest-embedded-arduino.rst

@@ -0,0 +1,28 @@
+#####################
+ pytest-embedded-idf
+#####################
+
+.. automodule:: pytest_embedded_idf.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_idf.dut
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_idf.linux
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_idf.serial
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_idf.unity_tester
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apis/pytest-embedded-idf.rst

@@ -0,0 +1,13 @@
+######################
+ pytest-embedded-jtag
+######################
+
+.. automodule:: pytest_embedded_jtag.gdb
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_jtag.openocd
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apis/pytest-embedded-jtag.rst

@@ -0,0 +1,18 @@
+######################
+ pytest-embedded-qemu
+######################
+
+.. automodule:: pytest_embedded_qemu.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_qemu.dut
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_qemu.qemu
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apis/pytest-embedded-qemu.rst

@@ -0,0 +1,8 @@
+############################
+ pytest-embedded-serial-esp
+############################
+
+.. automodule:: pytest_embedded_serial_esp.serial
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apis/pytest-embedded-serial-esp.rst

@@ -0,0 +1,13 @@
+########################
+ pytest-embedded-serial
+########################
+
+.. automodule:: pytest_embedded_serial.dut
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytest_embedded_serial.serial
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apis/pytest-embedded-serial.rst

@@ -0,0 +1,23 @@
+#######################
+ pytest-embedded-wokwi
+#######################
+
+.. automodule:: pytest_embedded_wokwi.arduino
+   :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:
+
+.. automodule:: pytest_embedded_wokwi.wokwi_cli
+   :members:
+   :undoc-members:
+   :show-inheritance: