[PATCH v8 00/21] dts: docstrings update

[Yoan Picchi]

On 11/23/23 15:13, Juraj Linkeš wrote:
> The first commit makes changes to the code. These code changes mainly
> change the structure of the code so that the actual API docs generation
> works. There are also some code changes which get reflected in the
> documentation, such as making functions/methods/attributes private or
> public.
> 
> The rest of the commits deal with the actual docstring documentation
> (from which the API docs are generated). The format of the docstrings
> is the Google format [0] with PEP257 [1] and some guidelines captured
> in the last commit of this group covering what the Google format
> doesn't.
> The docstring updates are split into many commits to make review
> possible. When accepted, they may be squashed.
> The docstrings have been composed in anticipation of [2], adhering to
> maximum line length of 100. We don't have a tool for automatic docstring
> formatting, hence the usage of 100 right away to save time.
> 
> NOTE: The logger.py module is not fully documented, as it's being
> refactored and the refactor will be submitted in the near future.
> Documenting it now seems unnecessary.
> 
> [0] https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in-classes
> [1] https://peps.python.org/pep-0257/
> [2] https://patches.dpdk.org/project/dpdk/list/?series=29844
> 
> v7:
> Split the series into docstrings and api docs generation and addressed
> comments.
> 
> v8:
> Addressed review comments, all of which were pretty minor - small
> gramatical changes, a little bit of rewording to remove confusion here
> and there, additional explanations and so on.
> 
> Juraj Linkeš (21):
>    dts: code adjustments for doc generation
>    dts: add docstring checker
>    dts: add basic developer docs
>    dts: exceptions docstring update
>    dts: settings docstring update
>    dts: logger and utils docstring update
>    dts: dts runner and main docstring update
>    dts: test suite docstring update
>    dts: test result docstring update
>    dts: config docstring update
>    dts: remote session docstring update
>    dts: interactive remote session docstring update
>    dts: port and virtual device docstring update
>    dts: cpu docstring update
>    dts: os session docstring update
>    dts: posix and linux sessions docstring update
>    dts: node docstring update
>    dts: sut and tg nodes docstring update
>    dts: base traffic generators docstring update
>    dts: scapy tg docstring update
>    dts: test suites docstring update
> 
>   doc/guides/tools/dts.rst                      |  73 +++
>   dts/framework/__init__.py                     |  12 +-
>   dts/framework/config/__init__.py              | 375 +++++++++++++---
>   dts/framework/config/types.py                 | 132 ++++++
>   dts/framework/dts.py                          | 162 +++++--
>   dts/framework/exception.py                    | 156 ++++---
>   dts/framework/logger.py                       |  72 ++-
>   dts/framework/remote_session/__init__.py      |  80 ++--
>   .../interactive_remote_session.py             |  36 +-
>   .../remote_session/interactive_shell.py       | 150 +++++++
>   dts/framework/remote_session/os_session.py    | 284 ------------
>   dts/framework/remote_session/python_shell.py  |  32 ++
>   .../remote_session/remote/__init__.py         |  27 --
>   .../remote/interactive_shell.py               | 131 ------
>   .../remote_session/remote/python_shell.py     |  12 -
>   .../remote_session/remote/remote_session.py   | 168 -------
>   .../remote_session/remote/testpmd_shell.py    |  45 --
>   .../remote_session/remote_session.py          | 230 ++++++++++
>   .../{remote => }/ssh_session.py               |  28 +-
>   dts/framework/remote_session/testpmd_shell.py |  83 ++++
>   dts/framework/settings.py                     | 188 ++++++--
>   dts/framework/test_result.py                  | 301 ++++++++++---
>   dts/framework/test_suite.py                   | 236 +++++++---
>   dts/framework/testbed_model/__init__.py       |  29 +-
>   dts/framework/testbed_model/{hw => }/cpu.py   | 209 ++++++---
>   dts/framework/testbed_model/hw/__init__.py    |  27 --
>   dts/framework/testbed_model/hw/port.py        |  60 ---
>   .../testbed_model/hw/virtual_device.py        |  16 -
>   .../linux_session.py                          |  70 ++-
>   dts/framework/testbed_model/node.py           | 214 ++++++---
>   dts/framework/testbed_model/os_session.py     | 422 ++++++++++++++++++
>   dts/framework/testbed_model/port.py           |  93 ++++
>   .../posix_session.py                          |  85 +++-
>   dts/framework/testbed_model/sut_node.py       | 238 ++++++----
>   dts/framework/testbed_model/tg_node.py        |  69 ++-
>   .../testbed_model/traffic_generator.py        |  72 ---
>   .../traffic_generator/__init__.py             |  43 ++
>   .../capturing_traffic_generator.py            |  49 +-
>   .../{ => traffic_generator}/scapy.py          | 110 +++--
>   .../traffic_generator/traffic_generator.py    |  85 ++++
>   dts/framework/testbed_model/virtual_device.py |  29 ++
>   dts/framework/utils.py                        | 122 ++---
>   dts/main.py                                   |  19 +-
>   dts/poetry.lock                               |  12 +-
>   dts/pyproject.toml                            |   6 +-
>   dts/tests/TestSuite_hello_world.py            |  16 +-
>   dts/tests/TestSuite_os_udp.py                 |  20 +-
>   dts/tests/TestSuite_smoke_tests.py            |  61 ++-
>   48 files changed, 3506 insertions(+), 1683 deletions(-)
>   create mode 100644 dts/framework/config/types.py
>   rename dts/framework/remote_session/{remote => }/interactive_remote_session.py (76%)
>   create mode 100644 dts/framework/remote_session/interactive_shell.py
>   delete mode 100644 dts/framework/remote_session/os_session.py
>   create mode 100644 dts/framework/remote_session/python_shell.py
>   delete mode 100644 dts/framework/remote_session/remote/__init__.py
>   delete mode 100644 dts/framework/remote_session/remote/interactive_shell.py
>   delete mode 100644 dts/framework/remote_session/remote/python_shell.py
>   delete mode 100644 dts/framework/remote_session/remote/remote_session.py
>   delete mode 100644 dts/framework/remote_session/remote/testpmd_shell.py
>   create mode 100644 dts/framework/remote_session/remote_session.py
>   rename dts/framework/remote_session/{remote => }/ssh_session.py (82%)
>   create mode 100644 dts/framework/remote_session/testpmd_shell.py
>   rename dts/framework/testbed_model/{hw => }/cpu.py (50%)
>   delete mode 100644 dts/framework/testbed_model/hw/__init__.py
>   delete mode 100644 dts/framework/testbed_model/hw/port.py
>   delete mode 100644 dts/framework/testbed_model/hw/virtual_device.py
>   rename dts/framework/{remote_session => testbed_model}/linux_session.py (77%)
>   create mode 100644 dts/framework/testbed_model/os_session.py
>   create mode 100644 dts/framework/testbed_model/port.py
>   rename dts/framework/{remote_session => testbed_model}/posix_session.py (73%)
>   delete mode 100644 dts/framework/testbed_model/traffic_generator.py
>   create mode 100644 dts/framework/testbed_model/traffic_generator/__init__.py
>   rename dts/framework/testbed_model/{ => traffic_generator}/capturing_traffic_generator.py (68%)
>   rename dts/framework/testbed_model/{ => traffic_generator}/scapy.py (71%)
>   create mode 100644 dts/framework/testbed_model/traffic_generator/traffic_generator.py
>   create mode 100644 dts/framework/testbed_model/virtual_device.py
> 
Reviewed-by: Yoan Picchi <yoan.picchi at arm.com>