Hi Bruce, Thomas,

The meson integration is kinda all over the place. I wanted to use the
existing conf.py Sphinx config file, but I also wanted to keep the docs
separated (because of extra DTS api docs dependencies), so the various
pieces are in different places (the config file in one place, meson code in
dts directory and generated Sphinx docs are in a new directory in the api
build dir, separate from the rest of the Sphinx html).

The big thing here is that I didn't figure out how to separate the dts api
build from the rest of the docs. I don't know how the -Denable_docs option
is supposed to work. I wanted to use -Denable_dts_docs in the same fashion
to decouple the builds, but it doesn't seem to work. Reading the code I
think the original option doesn't actually do anything - does it work? How
is it supposed to work?

Thanks,
Juraj

On Thu, Mar 23, 2023 at 11:40 AM Juraj Linkeš <juraj.linkes@pantheon.tech>
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 guide 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> doc
>
> There's only one properly documented module that serves as a
> demonstration of the style - framework.testbed_model.node.
>
> I didn't figure out how to separate dts build from the rest of the docs,
> which I think is required because of the different dependencies.
> I thought the enable_docs option would do this, so I added
> enable_dts_docs, but it doesn't seem to be working. Requesting comment
> on this.
>
> [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
>
>  doc/api/meson.build                           |   1 +
>  doc/guides/conf.py                            |  22 +-
>  doc/guides/meson.build                        |   1 +
>  doc/guides/tools/dts.rst                      |  29 +
>  doc/meson.build                               |   5 -
>  dts/doc-index.rst                             |  20 +
>  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                               |  50 ++
>  dts/poetry.lock                               | 770 ++++++++++++++++--
>  dts/pyproject.toml                            |   7 +
>  dts/tests/TestSuite_hello_world.py            |   6 +-
>  meson.build                                   |   6 +
>  meson_options.txt                             |   2 +
>  28 files changed, 1027 insertions(+), 225 deletions(-)
>  create mode 100644 dts/doc-index.rst
>  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
>
> --
> 2.30.2
>
>