mbox series

[v1,0/2] dts: api docs generation

Message ID 20231115133606.42081-1-juraj.linkes@pantheon.tech (mailing list archive)
Headers
Series dts: api docs generation |

Message

Juraj Linkeš Nov. 15, 2023, 1:36 p.m. UTC 
  The generation is done with Sphinx, which DPDK already uses, with
slightly modified configuration (the sidebar: unlimited depth and better
collapsing - I need comment on this).

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

This patchet depends on the series which updates the DTS docstrings. The
technical reason for this dependency is the hash value of the
poetry.lock file, which wouldn't match the contents were the patches to
be applied individually (the hash value would need to be recomputed
after applying the second patch).
The logical reason is that there's basically no point in generating the
documentation with the configuration in this patch series that's
tailored to the google format, which is contained in the depended
series. The generation would produce confusing errors and incomplete,
not good looking docs.

This patch series is much less important that the one updating the
docstrings. The docstrings series must be finished and applied as soon
as possible, as it has a dramatic impact on future development, while
this series doesn't hamper other development in any way.

Depends-on: series-30302 ("dts: docstrings update")

Juraj Linkeš (2):
  dts: add doc generation dependencies
  dts: add doc generation

 buildtools/call-sphinx-build.py |  29 +-
 doc/api/meson.build             |   1 +
 doc/guides/conf.py              |  34 ++-
 doc/guides/meson.build          |   1 +
 doc/guides/tools/dts.rst        |  32 +-
 dts/doc/conf_yaml_schema.json   |   1 +
 dts/doc/index.rst               |  17 ++
 dts/doc/meson.build             |  60 ++++
 dts/meson.build                 |  16 +
 dts/poetry.lock                 | 499 +++++++++++++++++++++++++++++++-
 dts/pyproject.toml              |   7 +
 meson.build                     |   1 +
 12 files changed, 681 insertions(+), 17 deletions(-)
 create mode 120000 dts/doc/conf_yaml_schema.json
 create mode 100644 dts/doc/index.rst
 create mode 100644 dts/doc/meson.build
 create mode 100644 dts/meson.build