On Fri, May 5, 2023 at 12:57 PM Bruce Richardson
<bruce.richard...@intel.com> wrote:
>
> 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.lin...@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.
>
I used meson 0.53.2 as that seemed to be the version I should target
(it's used in .ci/linux-setup.sh) which doesn't support the argument
(I originally wanted to use it, but they added it in 0.57.0). I didn't
see the error with 0.53.2.
Which version should I target? 1.0.1?
> > + 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'
> > +
