docs: small fixes

Author: hfudev

README.md

@@ -1,6 +1,6 @@
 # pytest-embedded
 
-[![Documentation Status](https://readthedocs.com/projects/espressif-pytest-embedded/badge/?version=latest)](https://docs.espressif.com/projects/pytest-embedded/en/latest/?badge=latest) ![Python 3.7+](https://img.shields.io/pypi/pyversions/pytest-embedded)
+[![Documentation Status](https://readthedocs.com/projects/espressif-pytest-embedded/badge/?version=latest)](https://docs.espressif.com/projects/pytest-embedded/en/latest/?badge=latest) ![Python 3.10+](https://img.shields.io/pypi/pyversions/pytest-embedded)
 
 A pytest plugin that has multiple services available for various functionalities. Designed for embedded testing.
 
@@ -17,15 +17,15 @@ A pytest plugin that has multiple services available for various functionalities
 
 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,
+It is recommended to use `~=2.0` to get rid of breaking changes, and use the latest new features. For example,
 
 ```shell
-pip install -U pytest-embedded~=1.0
+pip install -U pytest-embedded~=2.0
 ```
 
 ## Quickstart
 
-- `pip install -U pytest-embedded~=1.0`
+- `pip install -U pytest-embedded~=2.0`
 - Create a file `test_basic.py`
 
 ```python

docs/concepts/key-concepts.md

@@ -0,0 +1,151 @@
+##############
+ Key Concepts
+##############
+
+**********
+ Fixtures
+**********
+
+Each test case initializes a few fixtures. The most important fixtures are:
+
+-  ``msg_queue``: A message queue. A background listener process reads all messages from this queue, logs them to the terminal with an optional timestamp, and records them to the pexpect process.
+-  ``pexpect_proc``: A pexpect process that can run ``pexpect.expect()`` for testing purposes.
+-  ``app``: The built binary.
+-  ``dut``: Device Under Test (DUT). A DUT contains several daemon processes/threads, and the output of each is redirected to the ``msg_queue`` fixture.
+
+.. note::
+
+   You may redirect any output to the ``msg_queue`` fixture by ``contextlib.redirect_stdout``.
+
+   .. code:: python
+
+      import contextlib
+
+      def test_redirect(dut, msg_queue):
+          with contextlib.redirect_stdout(msg_queue):
+              print("will be redirected")
+
+          dut.expect_exact("redirected")
+
+   Or you may redirect the output from a fixture ``redirect``
+
+   .. code:: python
+
+      def test_redirect(dut, msg_queue, redirect):
+          with redirect():
+              print("will also be redirected")
+
+          dut.expect_exact("redirected")
+
+You can run ``pytest --fixtures`` to see all fixtures defined by ``pytest-embedded``. They are listed under the ``fixtures defined from pytest_embedded.plugin`` section.
+
+*****************
+ Parametrization
+*****************
+
+All CLI options support parametrization via ``indirect=True``. Parametrization is a feature provided by ``pytest``. For more details, please refer to the `Parametrizing tests <https://docs.pytest.org/en/stable/example/parametrize.html>`_ documentation.
+
+For example, running the ``pytest`` command with the following test script:
+
+.. code:: python
+
+   @pytest.mark.parametrize(
+       "embedded_services, app_path",
+       [
+           ("idf", app_path_1),
+           ("idf", app_path_2),
+       ],
+       indirect=True,
+   )
+   def test_serial_tcp(dut):
+       assert dut.app.target == "esp32"
+       dut.expect("Restart now")
+
+is equivalent to running two separate commands, ``pytest --embedded-services idf --app-path <app_path_1>`` and ``pytest --embedded-services idf --app-path <app_path_2>``, with this test script:
+
+.. code:: python
+
+   def test_serial_tcp(dut):
+       assert dut.app.target == "esp32"
+       dut.expect("Restart now")
+
+**********
+ Services
+**********
+
+You can activate additional services with ``pytest --embedded-services service[,service]`` to enable extra fixtures and functionalities. These services are provided by optional dependencies, which can be installed with ``pip``.
+
+Available services are described :doc:`here <services>`.
+
+************
+ Multi DUTs
+************
+
+Sometimes, you may need multiple DUTs for testing, for example, in master-slave or mesh network tests.
+
+Here are a few examples of how to enable this feature. For detailed information, refer to the ``embedded`` group in the ``pytest --help`` output.
+
+Enable multi DUTs by specifying ``--count``
+===========================================
+
+When multi-DUT mode is enabled, all fixtures become a tuple of instances. Each instance in the tuple is independent. For parametrization, each configuration uses ``|`` as a separator for each instance's values.
+
+For example, running shell command:
+
+.. code:: shell
+
+   pytest \
+   --embedded-services serial|serial \
+   --count 2 \
+   --app-path <master_bin>|<slave_bin>
+
+enables two DUTs with the ``serial`` service. The ``app`` fixture becomes a tuple of two ``App`` instances, and ``dut`` becomes a tuple of two ``Dut`` instances.
+
+You can test with:
+
+.. code:: python
+
+   def test(dut):
+       master = dut[0]
+       slave = dut[1]
+
+       master.expect("sent")
+       slave.expect("received")
+
+Specify once when applying to all DUTs
+======================================
+
+If all DUTs share the same configuration value, you only need to specify it once.
+
+.. code:: shell
+
+   pytest \
+   --embedded-services serial \
+   --count 2 \
+   --app-path <master_bin>|<slave_bin>
+
+The ``--embedded-services serial`` option applies to all DUTs.
+
+Vacant Value if it's Useless
+============================
+
+Sometimes, an option is only useful for a specific service. You can provide a vacant value if a configuration is not applicable to a particular DUT.
+
+.. code:: shell
+
+   pytest \
+   --embedded-services qemu|serial \
+   --count 2 \
+   --app-path <master_bin>|<slave_bin> \
+   --qemu-cli-args "<args>|" \
+   --port "|<port>"
+
+The ``--qemu-cli-args`` option applies to the first DUT (with the ``qemu`` service), while ``--port`` applies to the second DUT (with the ``serial`` service).
+
+*********
+ Logging
+*********
+
+``pytest-embedded`` prints all DUT output with a timestamp. To remove the timestamp, run pytest with the ``--with-timestamp n`` option.
+
+By default, ``pytest`` swallows ``stdout``. To see the live output, run pytest with the ``-s`` option.

docs/concepts/key-concepts.rst

@@ -12,8 +12,8 @@
 project_homepage = 'https://github.com/espressif/pytest-embedded'
 copyright = f'2023-{datetime.now().year}, Espressif Systems (Shanghai) Co., Ltd.'  # noqa: A001
 author = 'Fu Hanxi'
-version = '1.x'
-release = '1.x'
+version = '2.x'
+release = '2.x'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration