mbox

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

Message ID 20230323104040.484708-1-juraj.linkes@pantheon.tech (mailing list archive)
Headers

Message

Juraj Linkeš March 23, 2023, 10:40 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 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