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

build: remove unnecessary version checks

Since minimum meson version is now 0.57 we can remove all version checks
for versions lower than that.

Signed-off-by: Bruce Richardson <bruce.richardson@int

build: remove unnecessary version checks

Since minimum meson version is now 0.57 we can remove all version checks
for versions lower than that.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Reviewed-by: Robin Jarry <rjarry@redhat.com>
Tested-by: Ferruh Yigit <ferruh.yigit@amd.com>
Acked-by: Chengwen Feng <fengchengwen@huawei.com>

show more ...

doc: build API manpages as well as HTML output

Doxygen can produce manpage output as well as HTML output for the DPDK
APIs. However, we need to do this as a separate task as the manpage
output needs

doc: build API manpages as well as HTML output

Doxygen can produce manpage output as well as HTML output for the DPDK
APIs. However, we need to do this as a separate task as the manpage
output needs to be placed in a different location post-install to the
html output (/usr/local/share/man vs /usr/local/share/doc/).

Changes required are:
* Add configurable options for manpage output and html output to the
doxygen config template. (Remove option for html output path as it's
always "html")
* Modify API meson.build file to configure two separate doxygen config
files, for HTML and manpages respectively.
* Change doxygen wrapper script to have separate output log files for
the manpage and HTML jobs, to avoid conflicts
* Add "custom_targets" to meson.build file to build the HTML pages and
the manpages, with individual install locations for each.
* Where supported by meson version, call "mandb" post-install to update
the man database to ensure the new manpages can be found. If the
manpages are not installed in system location i.e. one not in MANPATH,
then this update will have no effect, as only system locations are
scanned.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Morten Brørup <mb@smartsharesystems.com>

show more ...

doc: rewrite shell scripts in Python

Shell used in documentation generation could not run on Windows.
Rewrite scripts in Python.
New scripts use proper path separators and handle paths with spaces.

doc: rewrite shell scripts in Python

Shell used in documentation generation could not run on Windows.
Rewrite scripts in Python.
New scripts use proper path separators and handle paths with spaces.

Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
Reviewed-by: Bruce Richardson <bruce.richardson@intel.com>

show more ...

doc: simplify CSS customization for Doxygen

CSS for API documentation was customized by a shell script
modifying the file that Doxygen produces.
This way CSS code is kept in a script and an extra bu

doc: simplify CSS customization for Doxygen

CSS for API documentation was customized by a shell script
modifying the file that Doxygen produces.
This way CSS code is kept in a script and an extra build step is added.
Move custom style to a plain CSS file.
Use Doxygen capability to attach this extra stylesheet.

Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>

show more ...

build: remove deprecated Meson functions

Starting in meson 0.56, the functions meson.source_root() and
meson.build_root() are deprecated and to be replaced by the [more
descriptive] functions: proje

build: remove deprecated Meson functions

Starting in meson 0.56, the functions meson.source_root() and
meson.build_root() are deprecated and to be replaced by the [more
descriptive] functions: project_source_root()/global_source_root() and
project_build_root()/global_build_root(). Unfortunately, these new
replacement functions were only added in 0.56 release too, so to use
them we would need version checks for old/new functions to remove the
deprecation warnings.

However, the functions "current_build_dir()" and "current_source_dir()"
remain unaffected by all this, so we can bypass the versioning problem,
by saving off these values to "dpdk_source_root" and "dpdk_build_root"
in the top-level meson.build file

Bugzilla ID: 926
Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Tested-by: Jerin Jacob <jerinj@marvell.com>

show more ...

doc: strip build artefacts for examples file list

examples.dox is built inside builddir/doc/api and so doxygen generates
some dir_HASH.html that includes the builddir name and this may prevent
DPDK

doc: strip build artefacts for examples file list

examples.dox is built inside builddir/doc/api and so doxygen generates
some dir_HASH.html that includes the builddir name and this may prevent
DPDK documentation to be correctly generated in some distributions, for
example CentOS Stream 9 and RHEL9, since the builddir includes the
architecture.

This commit adds builddir/doc/api (the path where examples.dox is
generated) to STRIP_FROM_PATH, so the generated documentation doesn't
change if builddir changes.

Fixes: a6090630f4e5 ("doc: automate examples file list for API")
Cc: stable@dpdk.org

Signed-off-by: Timothy Redaelli <tredaelli@redhat.com>
Acked-by: Luca Boccassi <bluca@debian.org>
Tested-by: David Marchand <david.marchand@redhat.com>

show more ...

build: change indentation in infrastructure files

Switch from using tabs to 4 spaces for meson.build indentation, for the
basic infrastructure and tooling files, as well as doc and kernel
directorie

build: change indentation in infrastructure files

Switch from using tabs to 4 spaces for meson.build indentation, for the
basic infrastructure and tooling files, as well as doc and kernel
directories.

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

show more ...

doc: add doxygen index file to dependencies

The doxygen index file is not printed as a processed file by doxygen so it
does not appear in the output .d (dependency file) list automatically
generated

doc: add doxygen index file to dependencies

The doxygen index file is not printed as a processed file by doxygen so it
does not appear in the output .d (dependency file) list automatically
generated. Therefore, for correct rebuild tracking, we need to explicitly
include it as a dependency of the doxygen job.

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

show more ...

doc: make doxygen comply with meson werror option

When the --werror meson build option is set, we can set the WARN_AS_ERRORS
doxygen option in the doxygen config flag to get the same behaviour for A

doc: make doxygen comply with meson werror option

When the --werror meson build option is set, we can set the WARN_AS_ERRORS
doxygen option in the doxygen config flag to get the same behaviour for API
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: align doxygen output folder with sphinx guides

The API docs were output to "<build>/doc/api/api" folder, which was
ugly-looking with the repeated "api", and inconsistent with the sphinx
guides

doc: align doxygen output folder with sphinx guides

The API docs were output to "<build>/doc/api/api" folder, which was
ugly-looking with the repeated "api", and inconsistent with the sphinx
guides which were written to "<build>/doc/guides/html". Changing the
doxygen output folder to "html" fixes both these issues.

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

show more ...

doc: add dependency on header files for API doxygen

Generate a dependency file for the header files used in the API guide
so that the docs can be rebuilt if a header changes.

Signed-off-by: Bruce R

doc: add dependency on header files for API doxygen

Generate a dependency file for the header files used in the API guide
so that the docs can be rebuilt if a header changes.

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

show more ...

doc: add dependency on examples for API doxygen

For the doxygen API for the examples folder, we can generate a build
dependency file when we generate the examples.dox file. This allows
correct rebui

doc: add dependency on examples for API doxygen

For the doxygen API for the examples folder, we can generate a build
dependency file when we generate the examples.dox file. This allows
correct rebuilds if the files in examples change.

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

show more ...

doc: reduce indentation in meson build file

When building the API docs, we can make the meson.build file easier to
read, and allow more code per line, by using subdir_done() to quit early.

Cc: stab

doc: reduce indentation in meson build file

When building the API docs, we can make the meson.build file easier to
read, and allow more code per line, by using subdir_done() to quit early.

Cc: stable@dpdk.org
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 ...

doc: fix warning with meson

The install parameter to configure_file is new in 0.50 and generates a
warning since it is newer than our minimum version of 0.47.1. The
parameter, however, is unneeded a

doc: fix warning with meson

The install parameter to configure_file is new in 0.50 and generates a
warning since it is newer than our minimum version of 0.47.1. The
parameter, however, is unneeded as the documentation states:

"When omitted it defaults to true when install_dir is set and not empty,
false otherwise."

Given that install_dir is not set for this file, install defaults to false
so no need to explicitly specify it.

Fixes: 720b14db3ae2 ("build: generate API documentation with meson")
Cc: stable@dpdk.org

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

doc: fix build with latest meson

The latest versions of meson don't build targets when build_by_default is
false but install is true, unlike older versions. We can fix this by having
both build_by_d

doc: fix build with latest meson

The latest versions of meson don't build targets when build_by_default is
false but install is true, unlike older versions. We can fix this by having
both build_by_default and install settings come from the build-time option.

Bugzilla ID: 303
Fixes: d02a2dab2dfb ("doc: support building HTML guides with meson")
Fixes: 720b14db3ae2 ("build: generate API documentation with meson")
Cc: stable@dpdk.org

Reported-by: Ali Alnubani <alialnu@mellanox.com>
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Luca Boccassi <bluca@debian.org>

show more ...

doc: support building HTML guides with meson

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: Luca Boccassi <bluca@debian.org>
Tested-by: Timothy Redaelli <tredaelli@redha

doc: support building HTML guides with meson

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: Luca Boccassi <bluca@debian.org>
Tested-by: Timothy Redaelli <tredaelli@redhat.com>

show more ...

build: generate API documentation with meson

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