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