doc: allow warnings in Sphinx for DTS

Sphinx-autodoc issues warnings about some symbols due to bad autodoc
"automock"ing when optional dependencies are missing:

Warning, treated as error:
Failed t

doc: allow warnings in Sphinx for DTS

Sphinx-autodoc issues warnings about some symbols due to bad autodoc
"automock"ing when optional dependencies are missing:

Warning, treated as error:
Failed to get a method signature for
framework.config.TestSuiteConfig.convert_from_string:
<classmethod(<function TestSuiteConfig.convert_from_string
at 0x7f1a4ec10790>)> is not a callable object

The current meson setup allows to treat warnings as errors, halting the
process and exiting early. Given these warnings should be ignored, this
patch removes this behavior. Until optional dependencies are detected,
warnings for DTS API docs will be checked manually as part of the DTS
approval process.

Fixes: 6597fa4a30ad ("dts: add autodoc Pydantic")

Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>

show more ...

dts: fix API doc directory and Doxygen link

Alias used to produce the link to the DTS API docs uses config data.
The required value in config data was being added in the wrong scope.
This moves the

dts: fix API doc directory and Doxygen link

Alias used to produce the link to the DTS API docs uses config data.
The required value in config data was being added in the wrong scope.
This moves the key addition to where the config data object is created.

DTS docs need to be placed in the same dir as main API docs.
Made DTS docs dependent on main docs and stopped separate install step
relying instead on the parent docs to install them.
This means they can no longer be build without main docs.

Added a line to sphinx python wrapper to create the destination path
if not already present.

Fixes: 7f9326423a04 ("dts: add API doc generation")

Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
Acked-by: Patrick Robb <probb@iol.unh.edu>
Reviewed-by: Dean Marx <dmarx@iol.unh.edu>
Reviewed-by: Nicholas Pratte <npratte@iol.unh.edu>
Reviewed-by: Patrick Robb <probb@iol.unh.edu>

show more ...

dts: add API doc generation

The tool used to generate DTS API docs is Sphinx, which is already in
use in DPDK. The same configuration is used to preserve style with one
DTS-specific configuration (s

dts: add API doc generation

The tool used to generate DTS API docs is Sphinx, which is already in
use in DPDK. The same configuration is used to preserve style with one
DTS-specific configuration (so that the DPDK docs are unchanged) that
modifies how the sidebar displays the content. There's other Sphinx
configuration related to Python docstrings which doesn't affect DPDK doc
build. All new configuration is in a conditional block, applied only
when DTS API docs are built to not interfere with DPDK doc build.

Sphinx generates the documentation from Python docstrings. The docstring
format is the Google format [0] which requires the sphinx.ext.napoleon
extension. The other extension, sphinx.ext.intersphinx, enables linking
to objects in external documentations, such as the Python documentation.

There is one requirement for building DTS docs - the same Python version
as DTS or higher, because Sphinx's autodoc extension imports the code.

The dependencies needed to import the code don't have to be satisfied,
as the autodoc extension allows us to mock the imports. The missing
packages are taken from the DTS pyproject.toml file.

And finally, the DTS API docs can be accessed from the DPDK API doxygen
page.

[0] https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Reviewed-by: Jeremy Spewock <jspewock@iol.unh.edu>
Reviewed-by: Dean Marx <dmarx@iol.unh.edu>
Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>

show more ...