mbox series

[v8,00/21] dts: docstrings update

Message ID 20231123151344.162812-1-juraj.linkes@pantheon.tech (mailing list archive)
Headers
Series dts: docstrings update |

Message

Juraj Linkeš Nov. 23, 2023, 3:13 p.m. UTC 
  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

Comments

Yoan Picchi Dec. 1, 2023, 4 p.m. UTC | #1 
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@arm.com>
Jeremy Spewock Dec. 1, 2023, 6:23 p.m. UTC | #2 
Hey Juraj,

I looked through all the patches and left a few comments. All of the
comments I left though were very minor comments about spelling/grammar on a
few patches. Otherwise this all looks good to me.