Re: [RFC PATCH v2 3/4] dts: add doc generation

[Bruce Richardson <bruce.richardson@intel.com>]

On Thu, May 04, 2023 at 02:37:48PM +0200, Juraj Linkeš wrote:
> The tool used to generate developer docs is sphinx, which is already
> used in DPDK. The configuration is kept the same to preserve the style.
> 
> Sphinx generates the documentation from Python docstrings. The docstring
> format most suitable for DTS seems to be the Google format [0] which
> requires the sphinx.ext.napoleon extension.
> 
> There are two requirements for building DTS docs:
> * The same Python version as DTS or higher, because Sphinx import the
>   code.
> * Also the same Python packages as DTS, for the same reason.
> 
> [0] https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
> 
> Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
> ---
>  doc/api/meson.build      |  1 +
>  doc/guides/conf.py       | 22 ++++++++++++++----
>  doc/guides/meson.build   |  1 +
>  doc/guides/tools/dts.rst | 29 +++++++++++++++++++++++
>  dts/doc/doc-index.rst    | 20 ++++++++++++++++
>  dts/doc/meson.build      | 50 ++++++++++++++++++++++++++++++++++++++++
>  dts/meson.build          | 16 +++++++++++++
>  meson.build              |  1 +
>  meson_options.txt        |  2 ++
>  9 files changed, 137 insertions(+), 5 deletions(-)
>  create mode 100644 dts/doc/doc-index.rst
>  create mode 100644 dts/doc/meson.build
>  create mode 100644 dts/meson.build
> 
<snip>

> diff --git a/dts/doc/meson.build b/dts/doc/meson.build
> new file mode 100644
> index 0000000000..db2bb0bed9
> --- /dev/null
> +++ b/dts/doc/meson.build
> @@ -0,0 +1,50 @@
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2023 PANTHEON.tech s.r.o.
> +
> +sphinx = find_program('sphinx-build', required: get_option('enable_dts_docs'))
> +sphinx_apidoc = find_program('sphinx-apidoc', required: get_option('enable_dts_docs'))
> +
> +if sphinx.found() and sphinx_apidoc.found()
> +endif
> +
> +dts_api_framework_dir = join_paths(dts_dir, 'framework')
> +dts_api_build_dir = join_paths(doc_api_build_dir, 'dts')
> +dts_api_src = custom_target('dts_api_src',
> +        output: 'modules.rst',
> +        command: ['SPHINX_APIDOC_OPTIONS=members,show-inheritance',

This gives errors when I try to configure a build, even without docs
enabled.

	~/dpdk.org$ meson setup build-test
	The Meson build system
	Version: 1.0.1
	Source dir: /home/bruce/dpdk.org
	...
	Program sphinx-build found: YES (/usr/bin/sphinx-build)
	Program sphinx-build found: YES (/usr/bin/sphinx-build)
	Program sphinx-apidoc found: YES (/usr/bin/sphinx-apidoc)

	dts/doc/meson.build:12:0: ERROR: Program 'SPHINX_APIDOC_OPTIONS=members,show-inheritance' not found or not executable

	A full log can be found at /home/bruce/dpdk.org/build-test/meson-logs/meson-log.txt

Assuming these need to be set in the environment, I think you can use the
"env" parameter to custom target instead.

> +            sphinx_apidoc, '--append-syspath', '--force',
> +            '--module-first', '--separate',
> +            '--doc-project', 'DTS', '-V', meson.project_version(),
> +            '-o', dts_api_build_dir,
> +            dts_api_framework_dir],
> +        build_by_default: get_option('enable_dts_docs'))
> +doc_targets += dts_api_src
> +doc_target_names += 'DTS_API_sphinx_sources'
> +