[RFC,v4,0/4] dts: add dts api docs

Message ID 20230831100407.59865-1-juraj.linkes@pantheon.tech (mailing list archive)
Headers
Series dts: add dts api docs |

Message

Juraj Linkeš Aug. 31, 2023, 10:04 a.m. UTC
Augment the meson build system with dts api generation. The api docs are
generated from Python docstrings in DTS using Sphinx. The format of
choice is the Google format [0].

The guides html sphinx configuration is used to preserve the same style,
except the sidebar is configured to allow unlimited depth and better
collapsing.

The build requires the same Python version and dependencies as DTS,
because Sphinx imports the Python modules. The modules are imported
individually, requiring code refactoring. Dependencies are installed
using Poetry from the dts directory:

poetry install --with docs

After installing, enter the Poetry shell:

poetry shell

And then run the build:
ninja -C <meson_build_dir> dts/doc

There's only one properly documented module that serves as a
demonstration of the style - framework.testbed_model.node. When we agree
on the docstring format, all docstrings will be reformatted.

[0] https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in-classes

Juraj Linkeš (4):
  dts: code adjustments for sphinx
  dts: add doc generation dependencies
  dts: add doc generation
  dts: format docstrigs to google format

 buildtools/call-sphinx-build.py               |  29 +-
 doc/api/meson.build                           |   1 +
 doc/guides/conf.py                            |  32 +-
 doc/guides/meson.build                        |   1 +
 doc/guides/tools/dts.rst                      |  29 ++
 dts/doc/doc-index.rst                         |  17 +
 dts/doc/meson.build                           |  50 ++
 dts/framework/config/__init__.py              |   3 -
 dts/framework/dts.py                          |  34 +-
 dts/framework/remote_session/__init__.py      |  41 +-
 .../interactive_remote_session.py             |   0
 .../{remote => }/interactive_shell.py         |   0
 .../{remote => }/python_shell.py              |   0
 .../remote_session/remote/__init__.py         |  27 --
 .../{remote => }/remote_session.py            |   0
 .../{remote => }/ssh_session.py               |   0
 .../{remote => }/testpmd_shell.py             |   0
 dts/framework/settings.py                     |  92 ++--
 dts/framework/test_suite.py                   |   3 +-
 dts/framework/testbed_model/__init__.py       |  12 +-
 dts/framework/testbed_model/common.py         |  29 ++
 dts/framework/testbed_model/{hw => }/cpu.py   |  13 +
 dts/framework/testbed_model/hw/__init__.py    |  27 --
 .../linux_session.py                          |   4 +-
 dts/framework/testbed_model/node.py           | 193 +++++---
 .../os_session.py                             |  14 +-
 dts/framework/testbed_model/{hw => }/port.py  |   0
 .../posix_session.py                          |   2 +-
 dts/framework/testbed_model/sut_node.py       |   8 +-
 dts/framework/testbed_model/tg_node.py        |  30 +-
 .../traffic_generator/__init__.py             |  24 +
 .../capturing_traffic_generator.py            |   2 +-
 .../{ => traffic_generator}/scapy.py          |  17 +-
 .../traffic_generator.py                      |  16 +-
 .../testbed_model/{hw => }/virtual_device.py  |   0
 dts/framework/utils.py                        |  53 +--
 dts/main.py                                   |   3 +-
 dts/meson.build                               |  16 +
 dts/poetry.lock                               | 447 +++++++++++++++++-
 dts/pyproject.toml                            |   7 +
 meson.build                                   |   1 +
 41 files changed, 961 insertions(+), 316 deletions(-)
 create mode 100644 dts/doc/doc-index.rst
 create mode 100644 dts/doc/meson.build
 rename dts/framework/remote_session/{remote => }/interactive_remote_session.py (100%)
 rename dts/framework/remote_session/{remote => }/interactive_shell.py (100%)
 rename dts/framework/remote_session/{remote => }/python_shell.py (100%)
 delete mode 100644 dts/framework/remote_session/remote/__init__.py
 rename dts/framework/remote_session/{remote => }/remote_session.py (100%)
 rename dts/framework/remote_session/{remote => }/ssh_session.py (100%)
 rename dts/framework/remote_session/{remote => }/testpmd_shell.py (100%)
 create mode 100644 dts/framework/testbed_model/common.py
 rename dts/framework/testbed_model/{hw => }/cpu.py (95%)
 delete mode 100644 dts/framework/testbed_model/hw/__init__.py
 rename dts/framework/{remote_session => testbed_model}/linux_session.py (98%)
 rename dts/framework/{remote_session => testbed_model}/os_session.py (97%)
 rename dts/framework/testbed_model/{hw => }/port.py (100%)
 rename dts/framework/{remote_session => testbed_model}/posix_session.py (99%)
 create mode 100644 dts/framework/testbed_model/traffic_generator/__init__.py
 rename dts/framework/testbed_model/{ => traffic_generator}/capturing_traffic_generator.py (99%)
 rename dts/framework/testbed_model/{ => traffic_generator}/scapy.py (96%)
 rename dts/framework/testbed_model/{ => traffic_generator}/traffic_generator.py (80%)
 rename dts/framework/testbed_model/{hw => }/virtual_device.py (100%)
 create mode 100644 dts/meson.build