dts: remove nested html directory for API doc

To facilitate deploying docs to the website
and make paths more consistent remove the html
directory from docs nested in API html directory.

Signed-off

dts: remove nested html directory for API doc

To facilitate deploying docs to the website
and make paths more consistent remove the html
directory from docs nested in API html directory.

Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>

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 ...

doc: copy custom CSS on guides build

The custom CSS file for Sphinx guides was copied during install,
but not during build time.
Before switching to Meson, the Makefile was copying this file
in the

doc: copy custom CSS on guides build

The custom CSS file for Sphinx guides was copied during install,
but not during build time.
Before switching to Meson, the Makefile was copying this file
in the build steps, so the doc was complete and viewable
from the build directory.

It is especially useful to get full documentation in the build directory
when building only documentation with "ninja -C build doc".
The command "ninja install" was required to get the CSS file installed,
but it requires to build the libraries as well.

The CSS file is now copied as part of the Sphinx build script,
and it will be installed as part of the whole html directory.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>

show more ...

doc: ensure Sphinx output is reproducible

By adding -j we build in parallel, to make building on multiprocessor
machines more effective. While that works it does also break
reproducible builds as th

doc: ensure Sphinx output is reproducible

By adding -j we build in parallel, to make building on multiprocessor
machines more effective. While that works it does also break
reproducible builds as the order of the sphinx generated searchindex.js
is depending on execution speed of the individual processes.

Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>

show more ...

doc: replace deprecated distutils version parsing

When using Python 3.10, this warning appears:
DeprecationWarning: The distutils package is deprecated
and slated for removal in Python 3.12.
U

doc: replace deprecated distutils version parsing

When using Python 3.10, this warning appears:
DeprecationWarning: The distutils package is deprecated
and slated for removal in Python 3.12.
Use setuptools or check PEP 632 for potential alternatives

The PEP 632 recommends replacing "distutils.version" with "packaging".

Bugzilla ID: 914
Cc: stable@dpdk.org

Reported-by: Jerin Jacob <jerinj@marvell.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Tested-by: Jerin Jacob <jerinj@marvell.com>

show more ...

doc: make sphinx comply with meson werror option

When the --werror meson build option is set, we can pass the "-W",
warning-as-errors, flag to sphinx to get the same behaviour for doc
building as fo

doc: make sphinx comply with meson werror option

When the --werror meson build option is set, we can pass the "-W",
warning-as-errors, flag to sphinx to get the same behaviour for doc
building as for building the rest of DPDK. This can help catch
documentation errors sooner in the development process.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

show more ...

doc: hide sphinx standard output

To see only errors and warnings from the doc builds, we can send the
standard output text to a logfile and have only the stderr messages
printed. This is similar to

doc: hide sphinx standard output

To see only errors and warnings from the doc builds, we can send the
standard output text to a logfile and have only the stderr messages
printed. This is similar to what is done for the API documentation.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

show more ...

doc: build without using make

When building the DPDK guide documents, the DPDK version information was
pulled using "make showversion", which meant there was a dependency on
the DPDK make-based buil

doc: build without using make

When building the DPDK guide documents, the DPDK version information was
pulled using "make showversion", which meant there was a dependency on
the DPDK make-based build system. Change this to have the version info
passed in from meson itself.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

show more ...

doc: fix build when sphinx reports version to stderr

When sphinx-build reports its version information to stderr rather
than stdout, the wrapper script misses it, and then fails to run.
We can fix t

doc: fix build when sphinx reports version to stderr

When sphinx-build reports its version information to stderr rather
than stdout, the wrapper script misses it, and then fails to run.
We can fix this by redirecting stderr to stdout for the version
query call.

Fixes: f5ab2074cfba ("doc: rebuild with meson whenever a file changes")
Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Tested-by: Ciara Power <ciara.power@intel.com>
Tested-by: David Marchand <david.marchand@redhat.com>

show more ...

doc: rebuild with meson whenever a file changes

Add proper support for calling sphinx whenever a file in the doc
directory changes. This is accomplished by using a wrapper script
for sphinx, which r

doc: rebuild with meson whenever a file changes

Add proper support for calling sphinx whenever a file in the doc
directory changes. This is accomplished by using a wrapper script
for sphinx, which runs sphinx but also emits a gcc-format dependency
file listing all the doc files. This is used by ninja so that any
change to the doc files triggers a rebuild of the docs.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Aaron Conole <aconole@redhat.com>
Acked-by: Luca Boccassi <bluca@debian.org>

show more ...