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

  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.

The build requires the same Python version and dependencies as DTS,
because Sphinx imports the Python modules. 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                            |  22 +-
 doc/guides/meson.build                        |   1 +
 doc/guides/tools/dts.rst                      |  29 +
 dts/doc/doc-index.rst                         |  20 +
 dts/doc/meson.build                           |  51 ++
 dts/framework/config/__init__.py              |  11 +
 .../{testbed_model/hw => config}/cpu.py       |  13 +
 dts/framework/dts.py                          |   8 +-
 dts/framework/remote_session/__init__.py      |   3 +-
 dts/framework/remote_session/linux_session.py |   2 +-
 dts/framework/remote_session/os_session.py    |  12 +-
 .../remote_session/remote/__init__.py         |  16 -
 .../{remote => }/remote_session.py            |   0
 .../{remote => }/ssh_session.py               |   0
 dts/framework/settings.py                     |  55 +-
 dts/framework/testbed_model/__init__.py       |  10 +-
 dts/framework/testbed_model/hw/__init__.py    |  27 -
 dts/framework/testbed_model/node.py           | 164 ++--
 dts/framework/testbed_model/sut_node.py       |   9 +-
 .../testbed_model/{hw => }/virtual_device.py  |   0
 dts/main.py                                   |   3 +-
 dts/meson.build                               |  16 +
 dts/poetry.lock                               | 770 ++++++++++++++++--
 dts/pyproject.toml                            |   7 +
 dts/tests/TestSuite_hello_world.py            |   6 +-
 meson.build                                   |   1 +
 meson_options.txt                             |   2 +
 29 files changed, 1058 insertions(+), 230 deletions(-)
 create mode 100644 dts/doc/doc-index.rst
 create mode 100644 dts/doc/meson.build
 rename dts/framework/{testbed_model/hw => config}/cpu.py (95%)
 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%)
 delete mode 100644 dts/framework/testbed_model/hw/__init__.py
 rename dts/framework/testbed_model/{hw => }/virtual_device.py (100%)
 create mode 100644 dts/meson.build
  

On Thu, May 11, 2023 at 11:14:04AM +0200, Juraj Linkeš wrote:
> 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.
> 
> The build requires the same Python version and dependencies as DTS,
> because Sphinx imports the Python modules. 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
> 
Given that building the DTS docs requires a special set of commands to set
things up and then to run the build through poetry, I think you should just
drop the option in meson_options.txt. I think it's better if building the
DTS docs is the steps that out outline here, and we don't try and integrate
it into the main DPDK build.

With that change:

Series-acked-by: Bruce Richardson <bruce.richardson@intel.com>
  

On Wed, May 17, 2023 at 6:57 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Thu, May 11, 2023 at 11:14:04AM +0200, Juraj Linkeš wrote:
> > 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.
> >
> > The build requires the same Python version and dependencies as DTS,
> > because Sphinx imports the Python modules. 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
> >
> Given that building the DTS docs requires a special set of commands to set
> things up and then to run the build through poetry, I think you should just
> drop the option in meson_options.txt. I think it's better if building the
> DTS docs is the steps that out outline here, and we don't try and integrate
> it into the main DPDK build.
>

That makes a lot of sense. I'll make the change.

> With that change:
>
> Series-acked-by: Bruce Richardson <bruce.richardson@intel.com>

Thanks.