[RFC,v2,3/4] dts: add doc generation
Checks
Commit Message
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
Comments
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',
> + 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'
> +
> +cp = find_program('cp', required: get_option('enable_docs'))
This should probably be "enable_dts_docs"
On Thu, May 4, 2023 at 2:45 PM Bruce Richardson
<bruce.richardson@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.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',
> > + 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'
> > +
> > +cp = find_program('cp', required: get_option('enable_docs'))
>
> This should probably be "enable_dts_docs"
>
Right, I overlooked that.
What do you think of the implementation in general?
On Fri, May 05, 2023 at 09:53:50AM +0200, Juraj Linkeš wrote:
> On Thu, May 4, 2023 at 2:45 PM Bruce Richardson
> <bruce.richardson@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.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',
> > > + 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'
> > > +
> > > +cp = find_program('cp', required: get_option('enable_docs'))
> >
> > This should probably be "enable_dts_docs"
> >
>
> Right, I overlooked that.
> What do you think of the implementation in general?
I need to download and apply the patches to test out before I comment on
that. I only gave them a quick scan thus far. I'll try and test them today
if I can.
/Bruce
On Fri, May 5, 2023 at 12:24 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Fri, May 05, 2023 at 09:53:50AM +0200, Juraj Linkeš wrote:
> > On Thu, May 4, 2023 at 2:45 PM Bruce Richardson
> > <bruce.richardson@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.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',
> > > > + 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'
> > > > +
> > > > +cp = find_program('cp', required: get_option('enable_docs'))
> > >
> > > This should probably be "enable_dts_docs"
> > >
> >
> > Right, I overlooked that.
> > What do you think of the implementation in general?
>
> I need to download and apply the patches to test out before I comment on
> that. I only gave them a quick scan thus far. I'll try and test them today
> if I can.
>
Great, thanks.
Juraj
> /Bruce
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'
> +
On Fri, May 5, 2023 at 12:57 PM Bruce Richardson
<bruce.richardson@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.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.
>
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'
> > +
On Fri, May 05, 2023 at 01:13:34PM +0200, Juraj Linkeš wrote:
> On Fri, May 5, 2023 at 12:57 PM Bruce Richardson
> <bruce.richardson@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.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.
> >
>
> 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'
> > > +
I didn't try with 0.53.2 - let me test that, see if the error goes away. We
may need different calls based on the meson version.
Is there no other way to pass this data rather than via the environment?
/Bruce
On Fri, May 5, 2023 at 3:29 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Fri, May 05, 2023 at 01:13:34PM +0200, Juraj Linkeš wrote:
> > On Fri, May 5, 2023 at 12:57 PM Bruce Richardson
> > <bruce.richardson@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.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.
> > >
> >
> > 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'
> > > > +
>
> I didn't try with 0.53.2 - let me test that, see if the error goes away. We
> may need different calls based on the meson version.
>
> Is there no other way to pass this data rather than via the environment?
>
Certainly. For background, I wanted to do the same thing we do for
DPDK_VERSION, but that would require adding an additional parameter to
call-sphinx-build.py, which wouldn't be used by the other call of
call-sphinx-build.py (the one that builds doc guides), so I skipped
the parameter and set the env var before the call.
There are a few options that come to mind:
1. Use the parameter. There are two sub-options here, either make the
parameter positional and mandatory and then we'd have an awkward call
that builds the guides or I could make it optional, but that would
make the script a bit more complex (some argparse logic would be
needed).
2. Hard-code the path into conf.py.
3. Have separate conf.py files. Maybe we could make this work with symlinks.
There could be something else. I like adding the optional parameter. I
don't know the policy on buildtools script complexity so let me know
what you think.
Juraj
> /Bruce
On Tue, May 09, 2023 at 11:23:50AM +0200, Juraj Linkeš wrote:
> On Fri, May 5, 2023 at 3:29 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > On Fri, May 05, 2023 at 01:13:34PM +0200, Juraj Linkeš wrote:
> > > On Fri, May 5, 2023 at 12:57 PM Bruce Richardson
> > > <bruce.richardson@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.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.
> > > >
> > >
> > > 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'
> > > > > +
> >
> > I didn't try with 0.53.2 - let me test that, see if the error goes away. We
> > may need different calls based on the meson version.
> >
> > Is there no other way to pass this data rather than via the environment?
> >
>
> Certainly. For background, I wanted to do the same thing we do for
> DPDK_VERSION, but that would require adding an additional parameter to
> call-sphinx-build.py, which wouldn't be used by the other call of
> call-sphinx-build.py (the one that builds doc guides), so I skipped
> the parameter and set the env var before the call.
>
> There are a few options that come to mind:
> 1. Use the parameter. There are two sub-options here, either make the
> parameter positional and mandatory and then we'd have an awkward call
> that builds the guides or I could make it optional, but that would
> make the script a bit more complex (some argparse logic would be
> needed).
> 2. Hard-code the path into conf.py.
> 3. Have separate conf.py files. Maybe we could make this work with symlinks.
>
> There could be something else. I like adding the optional parameter. I
> don't know the policy on buildtools script complexity so let me know
> what you think.
>
If the parameter would be just unused for the main doc build, and cause no
issues, I don't see why we can't just put it into the main conf.py file. We
can add a comment explaining that it only applies for the DTS doc. However,
option 1, with an extra optional parameter doesn't seem so bad to me
either. Using argparse in the build script doesn't seem like a problem
either, if it's necessary. Maybe others have other opinions, though.
/Bruce
On Tue, May 9, 2023 at 11:40 AM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Tue, May 09, 2023 at 11:23:50AM +0200, Juraj Linkeš wrote:
> > On Fri, May 5, 2023 at 3:29 PM Bruce Richardson
> > <bruce.richardson@intel.com> wrote:
> > >
> > > On Fri, May 05, 2023 at 01:13:34PM +0200, Juraj Linkeš wrote:
> > > > On Fri, May 5, 2023 at 12:57 PM Bruce Richardson
> > > > <bruce.richardson@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.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.
> > > > >
> > > >
> > > > 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'
> > > > > > +
> > >
> > > I didn't try with 0.53.2 - let me test that, see if the error goes away. We
> > > may need different calls based on the meson version.
> > >
> > > Is there no other way to pass this data rather than via the environment?
> > >
> >
> > Certainly. For background, I wanted to do the same thing we do for
> > DPDK_VERSION, but that would require adding an additional parameter to
> > call-sphinx-build.py, which wouldn't be used by the other call of
> > call-sphinx-build.py (the one that builds doc guides), so I skipped
> > the parameter and set the env var before the call.
> >
> > There are a few options that come to mind:
> > 1. Use the parameter. There are two sub-options here, either make the
> > parameter positional and mandatory and then we'd have an awkward call
> > that builds the guides or I could make it optional, but that would
> > make the script a bit more complex (some argparse logic would be
> > needed).
> > 2. Hard-code the path into conf.py.
> > 3. Have separate conf.py files. Maybe we could make this work with symlinks.
> >
> > There could be something else. I like adding the optional parameter. I
> > don't know the policy on buildtools script complexity so let me know
> > what you think.
> >
> If the parameter would be just unused for the main doc build, and cause no
> issues, I don't see why we can't just put it into the main conf.py file. We
> can add a comment explaining that it only applies for the DTS doc. However,
> option 1, with an extra optional parameter doesn't seem so bad to me
> either. Using argparse in the build script doesn't seem like a problem
> either, if it's necessary. Maybe others have other opinions, though.
>
I'll just submit the version with argparse and we'll see how it looks.
> /Bruce
@@ -1,6 +1,7 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+doc_api_build_dir = meson.current_build_dir()
doxygen = find_program('doxygen', required: get_option('enable_docs'))
if not doxygen.found()
@@ -7,10 +7,9 @@
from sphinx import __version__ as sphinx_version
from os import listdir
from os import environ
-from os.path import basename
-from os.path import dirname
+from os.path import basename, dirname
from os.path import join as path_join
-from sys import argv, stderr
+from sys import argv, stderr, path
import configparser
@@ -24,6 +23,19 @@
file=stderr)
pass
+extensions = ['sphinx.ext.napoleon']
+
+# Python docstring options
+autodoc_member_order = 'bysource'
+autodoc_typehints = 'both'
+autodoc_typehints_format = 'short'
+napoleon_numpy_docstring = False
+napoleon_attr_annotations = True
+napoleon_use_ivar = True
+napoleon_use_rtype = False
+add_module_names = False
+toc_object_entries_show_parents = 'hide'
+
stop_on_error = ('-W' in argv)
project = 'Data Plane Development Kit'
@@ -35,8 +47,8 @@
html_show_copyright = False
highlight_language = 'none'
-release = environ.setdefault('DPDK_VERSION', "None")
-version = release
+path.append(environ.setdefault('DTS_ROOT', '.'))
+version = environ.setdefault('DPDK_VERSION', "None")
master_doc = 'index'
@@ -1,6 +1,7 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright(c) 2018 Intel Corporation
+doc_guides_source_dir = meson.current_source_dir()
sphinx = find_program('sphinx-build', required: get_option('enable_docs'))
if not sphinx.found()
@@ -282,3 +282,32 @@ There are three tools used in DTS to help with code checking, style and formatti
These three tools are all used in ``devtools/dts-check-format.sh``,
the DTS code check and format script.
Refer to the script for usage: ``devtools/dts-check-format.sh -h``.
+
+
+Building DTS API docs
+---------------------
+
+To build DTS API docs, install the dependencies with Poetry, then enter its shell:
+
+ .. code-block:: console
+
+ poetry install --with docs
+ poetry shell
+
+
+Build commands
+~~~~~~~~~~~~~~
+
+The documentation is built using the standard DPDK build system.
+
+After entering Poetry's shell, build the documentation with:
+
+ .. code-block:: console
+
+ ninja -C build dts/doc
+
+The output is generated in ``build/doc/api/dts/html``.
+
+.. Note::
+
+ Make sure to fix any Sphinx warnings when adding or updating docstrings.
new file mode 100644
@@ -0,0 +1,20 @@
+.. DPDK Test Suite documentation master file, created by
+ sphinx-quickstart on Tue Mar 14 12:23:52 2023.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to DPDK Test Suite's documentation!
+===========================================
+
+.. toctree::
+ :maxdepth: 4
+ :caption: Contents:
+
+ modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
new file mode 100644
@@ -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',
+ 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'
+
+cp = find_program('cp', required: get_option('enable_docs'))
+cp_index = custom_target('cp_index',
+ input: 'doc-index.rst',
+ output: 'index.rst',
+ depends: dts_api_src,
+ command: [cp, '@INPUT@', join_paths(dts_api_build_dir, 'index.rst')],
+ build_by_default: get_option('enable_dts_docs'))
+doc_targets += cp_index
+doc_target_names += 'DTS_API_sphinx_index'
+
+extra_sphinx_args = ['-a', '-c', doc_guides_source_dir]
+if get_option('werror')
+ extra_sphinx_args += '-W'
+endif
+
+htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
+dts_api_html = custom_target('dts_api_html',
+ output: 'html',
+ depends: cp_index,
+ command: ['DTS_ROOT=@0@'.format(dts_dir),
+ sphinx_wrapper, sphinx, meson.project_version(),
+ dts_api_build_dir, dts_api_build_dir, extra_sphinx_args],
+ build_by_default: get_option('enable_dts_docs'),
+ install: get_option('enable_dts_docs'),
+ install_dir: htmldir)
+doc_targets += dts_api_html
+doc_target_names += 'DTS_API_HTML'
new file mode 100644
@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2023 PANTHEON.tech s.r.o.
+
+doc_targets = []
+doc_target_names = []
+dts_dir = meson.current_source_dir()
+
+subdir('doc')
+
+if doc_targets.length() == 0
+ message = 'No docs targets found'
+else
+ message = 'Built docs:'
+endif
+run_target('dts/doc', command: [echo, message, doc_target_names],
+ depends: doc_targets)
@@ -84,6 +84,7 @@ subdir('app')
# build docs
subdir('doc')
+subdir('dts')
# build any examples explicitly requested - useful for developers - and
# install any example code into the appropriate install path
@@ -16,6 +16,8 @@ option('drivers_install_subdir', type: 'string', value: 'dpdk/pmds-<VERSION>', d
'Subdirectory of libdir where to install PMDs. Defaults to using a versioned subdirectory.')
option('enable_docs', type: 'boolean', value: false, description:
'build documentation')
+option('enable_dts_docs', type: 'boolean', value: false, description:
+ 'Build DTS API documentation.')
option('enable_apps', type: 'string', value: '', description:
'Comma-separated list of apps to build. If unspecified, build all apps.')
option('enable_drivers', type: 'string', value: '', description: