[PATCH v12 0/5] dts: API docs generation

["Juraj Linkeš" <juraj.linkes@pantheon.tech>]

The generation is done with Sphinx, which DPDK already uses, with
slightly modified configuration of the sidebar present in an if block.

DTS dependencies do not need to be installed, but there is the option to
install doc build dependencies with Poetry:
poetry install --with docs

The build itself may be run with:
meson setup <meson_build_dir> -Denable_docs=true
ninja -C <meson_build_dir>

The above will do a full DPDK build with docs. To build just docs:
meson setup <meson_build_dir>
ninja -C <meson_build_dir> dts-doc

Python3.10 is required to build the DTS API docs.

The patchset contains the .rst sources which Sphinx uses to generate the
html pages. These were first generated with the sphinx-apidoc utility
and modified to provide a better look. The documentation just doesn't
look that good without the modifications and there isn't enough
configuration options to achieve that without manual changes to the .rst
files. This introduces extra maintenance which involves adding new .rst
files when a new Python module is added or changing the .rst structure
if the Python directory/file structure is changed (moved, renamed
files). This small maintenance burden is outweighed by the flexibility
afforded by the ability to make manual changes to the .rst files.

v10:
Fix dts doc generation issue: Only copy the custom rss file if it exists.

v11:
Added the config option autodoc_mock_imports, which eliminates the need
for DTS dependencies. Added a script that find out which imports need to
be added to autodoc_mock_imports. The script also check the required
Python version for building DTS docs.
Removed tags from the two affected patches which will need to be
reviewed again.

v12:
Added paramiko to the required dependencies of get-dts-deps.py.

Juraj Linkeš (5):
  dts: update params and parser docstrings
  dts: add doc generation dependencies
  dts: add API doc sources
  doc: meson doc API build dir variable
  dts: add API doc generation

 buildtools/call-sphinx-build.py               |  10 +-
 buildtools/get-dts-deps.py                    |  78 +++
 buildtools/meson.build                        |   1 +
 doc/api/doxy-api-index.md                     |   3 +
 doc/api/doxy-api.conf.in                      |   2 +
 doc/api/meson.build                           |   8 +-
 doc/guides/conf.py                            |  41 +-
 doc/guides/contributing/documentation.rst     |   2 +
 doc/guides/contributing/patches.rst           |   4 +
 doc/guides/meson.build                        |   1 +
 doc/guides/tools/dts.rst                      |  39 +-
 dts/doc/conf_yaml_schema.json                 |   1 +
 dts/doc/framework.config.rst                  |  12 +
 dts/doc/framework.config.types.rst            |   6 +
 dts/doc/framework.exception.rst               |   6 +
 dts/doc/framework.logger.rst                  |   6 +
 dts/doc/framework.params.eal.rst              |   6 +
 dts/doc/framework.params.rst                  |  14 +
 dts/doc/framework.params.testpmd.rst          |   6 +
 dts/doc/framework.params.types.rst            |   6 +
 dts/doc/framework.parser.rst                  |   6 +
 .../framework.remote_session.dpdk_shell.rst   |   6 +
 ...ote_session.interactive_remote_session.rst |   6 +
 ...ework.remote_session.interactive_shell.rst |   6 +
 .../framework.remote_session.python_shell.rst |   6 +
 ...ramework.remote_session.remote_session.rst |   6 +
 dts/doc/framework.remote_session.rst          |  18 +
 .../framework.remote_session.ssh_session.rst  |   6 +
 ...framework.remote_session.testpmd_shell.rst |   6 +
 dts/doc/framework.runner.rst                  |   6 +
 dts/doc/framework.settings.rst                |   6 +
 dts/doc/framework.test_result.rst             |   6 +
 dts/doc/framework.test_suite.rst              |   6 +
 dts/doc/framework.testbed_model.cpu.rst       |   6 +
 .../framework.testbed_model.linux_session.rst |   6 +
 dts/doc/framework.testbed_model.node.rst      |   6 +
 .../framework.testbed_model.os_session.rst    |   6 +
 dts/doc/framework.testbed_model.port.rst      |   6 +
 .../framework.testbed_model.posix_session.rst |   6 +
 dts/doc/framework.testbed_model.rst           |  26 +
 dts/doc/framework.testbed_model.sut_node.rst  |   6 +
 dts/doc/framework.testbed_model.tg_node.rst   |   6 +
 ..._generator.capturing_traffic_generator.rst |   6 +
 ...mework.testbed_model.traffic_generator.rst |  14 +
 ....testbed_model.traffic_generator.scapy.rst |   6 +
 ...el.traffic_generator.traffic_generator.rst |   6 +
 ...framework.testbed_model.virtual_device.rst |   6 +
 dts/doc/framework.utils.rst                   |   6 +
 dts/doc/index.rst                             |  43 ++
 dts/doc/meson.build                           |  30 +
 dts/framework/params/__init__.py              |   4 +-
 dts/framework/params/eal.py                   |   7 +-
 dts/framework/params/types.py                 |   3 +-
 dts/framework/parser.py                       |   4 +-
 dts/meson.build                               |  15 +
 dts/poetry.lock                               | 521 +++++++++++++++++-
 dts/pyproject.toml                            |   8 +
 meson.build                                   |   1 +
 58 files changed, 1071 insertions(+), 25 deletions(-)
 create mode 100755 buildtools/get-dts-deps.py
 create mode 120000 dts/doc/conf_yaml_schema.json
 create mode 100644 dts/doc/framework.config.rst
 create mode 100644 dts/doc/framework.config.types.rst
 create mode 100644 dts/doc/framework.exception.rst
 create mode 100644 dts/doc/framework.logger.rst
 create mode 100644 dts/doc/framework.params.eal.rst
 create mode 100644 dts/doc/framework.params.rst
 create mode 100644 dts/doc/framework.params.testpmd.rst
 create mode 100644 dts/doc/framework.params.types.rst
 create mode 100644 dts/doc/framework.parser.rst
 create mode 100644 dts/doc/framework.remote_session.dpdk_shell.rst
 create mode 100644 dts/doc/framework.remote_session.interactive_remote_session.rst
 create mode 100644 dts/doc/framework.remote_session.interactive_shell.rst
 create mode 100644 dts/doc/framework.remote_session.python_shell.rst
 create mode 100644 dts/doc/framework.remote_session.remote_session.rst
 create mode 100644 dts/doc/framework.remote_session.rst
 create mode 100644 dts/doc/framework.remote_session.ssh_session.rst
 create mode 100644 dts/doc/framework.remote_session.testpmd_shell.rst
 create mode 100644 dts/doc/framework.runner.rst
 create mode 100644 dts/doc/framework.settings.rst
 create mode 100644 dts/doc/framework.test_result.rst
 create mode 100644 dts/doc/framework.test_suite.rst
 create mode 100644 dts/doc/framework.testbed_model.cpu.rst
 create mode 100644 dts/doc/framework.testbed_model.linux_session.rst
 create mode 100644 dts/doc/framework.testbed_model.node.rst
 create mode 100644 dts/doc/framework.testbed_model.os_session.rst
 create mode 100644 dts/doc/framework.testbed_model.port.rst
 create mode 100644 dts/doc/framework.testbed_model.posix_session.rst
 create mode 100644 dts/doc/framework.testbed_model.rst
 create mode 100644 dts/doc/framework.testbed_model.sut_node.rst
 create mode 100644 dts/doc/framework.testbed_model.tg_node.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.scapy.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst
 create mode 100644 dts/doc/framework.testbed_model.virtual_device.rst
 create mode 100644 dts/doc/framework.utils.rst
 create mode 100644 dts/doc/index.rst
 create mode 100644 dts/doc/meson.build
 create mode 100644 dts/meson.build

-- 
2.34.1