[RFC,v1,0/4] dts: add dts api docs

  Augment the meson build system with dts api generation. The api docs are
generated from Python docstrings in DTS using Sphinx. The format of
choice is the Google format [0].

The guide html sphinx configuration is used to preserve the same style.

The build requires the same Python version and dependencies as DTS,
because Sphinx imports the Python modules. Dependencies are installed
using Poetry from the dts directory:

poetry install --with docs

After installing, enter the Poetry shell:

poetry shell

And then run the build:
ninja -C <meson_build_dir> doc

There's only one properly documented module that serves as a
demonstration of the style - framework.testbed_model.node.

I didn't figure out how to separate dts build from the rest of the docs,
which I think is required because of the different dependencies.
I thought the enable_docs option would do this, so I added
enable_dts_docs, but it doesn't seem to be working. Requesting comment
on this.

[0] https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in-classes

Juraj Linkeš (4):
  dts: code adjustments for sphinx
  dts: add doc generation dependencies
  dts: add doc generation
  dts: format docstrigs to google format

 doc/api/meson.build                           |   1 +
 doc/guides/conf.py                            |  22 +-
 doc/guides/meson.build                        |   1 +
 doc/guides/tools/dts.rst                      |  29 +
 doc/meson.build                               |   5 -
 dts/doc-index.rst                             |  20 +
 dts/framework/config/__init__.py              |  11 +
 .../{testbed_model/hw => config}/cpu.py       |  13 +
 dts/framework/dts.py                          |   8 +-
 dts/framework/remote_session/__init__.py      |   3 +-
 dts/framework/remote_session/linux_session.py |   2 +-
 dts/framework/remote_session/os_session.py    |  12 +-
 .../remote_session/remote/__init__.py         |  16 -
 .../{remote => }/remote_session.py            |   0
 .../{remote => }/ssh_session.py               |   0
 dts/framework/settings.py                     |  55 +-
 dts/framework/testbed_model/__init__.py       |  10 +-
 dts/framework/testbed_model/hw/__init__.py    |  27 -
 dts/framework/testbed_model/node.py           | 164 ++--
 dts/framework/testbed_model/sut_node.py       |   9 +-
 .../testbed_model/{hw => }/virtual_device.py  |   0
 dts/main.py                                   |   3 +-
 dts/meson.build                               |  50 ++
 dts/poetry.lock                               | 770 ++++++++++++++++--
 dts/pyproject.toml                            |   7 +
 dts/tests/TestSuite_hello_world.py            |   6 +-
 meson.build                                   |   6 +
 meson_options.txt                             |   2 +
 28 files changed, 1027 insertions(+), 225 deletions(-)
 create mode 100644 dts/doc-index.rst
 rename dts/framework/{testbed_model/hw => config}/cpu.py (95%)
 delete mode 100644 dts/framework/remote_session/remote/__init__.py
 rename dts/framework/remote_session/{remote => }/remote_session.py (100%)
 rename dts/framework/remote_session/{remote => }/ssh_session.py (100%)
 delete mode 100644 dts/framework/testbed_model/hw/__init__.py
 rename dts/framework/testbed_model/{hw => }/virtual_device.py (100%)
 create mode 100644 dts/meson.build
  

Hi Bruce, Thomas,

The meson integration is kinda all over the place. I wanted to use the
existing conf.py Sphinx config file, but I also wanted to keep the docs
separated (because of extra DTS api docs dependencies), so the various
pieces are in different places (the config file in one place, meson code in
dts directory and generated Sphinx docs are in a new directory in the api
build dir, separate from the rest of the Sphinx html).

The big thing here is that I didn't figure out how to separate the dts api
build from the rest of the docs. I don't know how the -Denable_docs option
is supposed to work. I wanted to use -Denable_dts_docs in the same fashion
to decouple the builds, but it doesn't seem to work. Reading the code I
think the original option doesn't actually do anything - does it work? How
is it supposed to work?

Thanks,
Juraj

On Thu, Mar 23, 2023 at 11:40 AM Juraj Linkeš <juraj.linkes@pantheon.tech>
wrote:

> Augment the meson build system with dts api generation. The api docs are
> generated from Python docstrings in DTS using Sphinx. The format of
> choice is the Google format [0].
>
> The guide html sphinx configuration is used to preserve the same style.
>
> The build requires the same Python version and dependencies as DTS,
> because Sphinx imports the Python modules. Dependencies are installed
> using Poetry from the dts directory:
>
> poetry install --with docs
>
> After installing, enter the Poetry shell:
>
> poetry shell
>
> And then run the build:
> ninja -C <meson_build_dir> doc
>
> There's only one properly documented module that serves as a
> demonstration of the style - framework.testbed_model.node.
>
> I didn't figure out how to separate dts build from the rest of the docs,
> which I think is required because of the different dependencies.
> I thought the enable_docs option would do this, so I added
> enable_dts_docs, but it doesn't seem to be working. Requesting comment
> on this.
>
> [0]
> https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in-classes
>
> Juraj Linkeš (4):
>   dts: code adjustments for sphinx
>   dts: add doc generation dependencies
>   dts: add doc generation
>   dts: format docstrigs to google format
>
>  doc/api/meson.build                           |   1 +
>  doc/guides/conf.py                            |  22 +-
>  doc/guides/meson.build                        |   1 +
>  doc/guides/tools/dts.rst                      |  29 +
>  doc/meson.build                               |   5 -
>  dts/doc-index.rst                             |  20 +
>  dts/framework/config/__init__.py              |  11 +
>  .../{testbed_model/hw => config}/cpu.py       |  13 +
>  dts/framework/dts.py                          |   8 +-
>  dts/framework/remote_session/__init__.py      |   3 +-
>  dts/framework/remote_session/linux_session.py |   2 +-
>  dts/framework/remote_session/os_session.py    |  12 +-
>  .../remote_session/remote/__init__.py         |  16 -
>  .../{remote => }/remote_session.py            |   0
>  .../{remote => }/ssh_session.py               |   0
>  dts/framework/settings.py                     |  55 +-
>  dts/framework/testbed_model/__init__.py       |  10 +-
>  dts/framework/testbed_model/hw/__init__.py    |  27 -
>  dts/framework/testbed_model/node.py           | 164 ++--
>  dts/framework/testbed_model/sut_node.py       |   9 +-
>  .../testbed_model/{hw => }/virtual_device.py  |   0
>  dts/main.py                                   |   3 +-
>  dts/meson.build                               |  50 ++
>  dts/poetry.lock                               | 770 ++++++++++++++++--
>  dts/pyproject.toml                            |   7 +
>  dts/tests/TestSuite_hello_world.py            |   6 +-
>  meson.build                                   |   6 +
>  meson_options.txt                             |   2 +
>  28 files changed, 1027 insertions(+), 225 deletions(-)
>  create mode 100644 dts/doc-index.rst
>  rename dts/framework/{testbed_model/hw => config}/cpu.py (95%)
>  delete mode 100644 dts/framework/remote_session/remote/__init__.py
>  rename dts/framework/remote_session/{remote => }/remote_session.py (100%)
>  rename dts/framework/remote_session/{remote => }/ssh_session.py (100%)
>  delete mode 100644 dts/framework/testbed_model/hw/__init__.py
>  rename dts/framework/testbed_model/{hw => }/virtual_device.py (100%)
>  create mode 100644 dts/meson.build
>
> --
> 2.30.2
>
>
  

On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote:
>    Hi Bruce, Thomas,
>    The meson integration is kinda all over the place. I wanted to use the
>    existing conf.py Sphinx config file, but I also wanted to keep the docs
>    separated (because of extra DTS api docs dependencies), so the various
>    pieces are in different places (the config file in one place, meson
>    code in dts directory and generated Sphinx docs are in a new directory
>    in the api build dir, separate from the rest of the Sphinx html).
>    The big thing here is that I didn't figure out how to separate the dts
>    api build from the rest of the docs. I don't know how the -Denable_docs
>    option is supposed to work. I wanted to use -Denable_dts_docs in the
>    same fashion to decouple the builds, but it doesn't seem to work.
>    Reading the code I think the original option doesn't actually do
>    anything - does it work? How is it supposed to work?
>    Thanks,
>    Juraj

The enable_docs option works by selectively enabling the doc build tasks
using the "build_by_default" parameter on them. 
See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an
example. The custom_target for sphinx is not a dependency of any other
task, so whether it gets run or not depends entirely on whether the
"build_by_default" and/or "install" options are set.

As usual, there may be other stuff that needs cleaning up on this, but
that's how it works for now, anyway. [And it does actually work, last I
tested it :-)]

/Bruce
  

On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote:
> >    Hi Bruce, Thomas,
> >    The meson integration is kinda all over the place. I wanted to use the
> >    existing conf.py Sphinx config file, but I also wanted to keep the docs
> >    separated (because of extra DTS api docs dependencies), so the various
> >    pieces are in different places (the config file in one place, meson
> >    code in dts directory and generated Sphinx docs are in a new directory
> >    in the api build dir, separate from the rest of the Sphinx html).
> >    The big thing here is that I didn't figure out how to separate the dts
> >    api build from the rest of the docs. I don't know how the -Denable_docs
> >    option is supposed to work. I wanted to use -Denable_dts_docs in the
> >    same fashion to decouple the builds, but it doesn't seem to work.
> >    Reading the code I think the original option doesn't actually do
> >    anything - does it work? How is it supposed to work?
> >    Thanks,
> >    Juraj
>
> The enable_docs option works by selectively enabling the doc build tasks
> using the "build_by_default" parameter on them.
> See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an
> example. The custom_target for sphinx is not a dependency of any other
> task, so whether it gets run or not depends entirely on whether the
> "build_by_default" and/or "install" options are set.
>
> As usual, there may be other stuff that needs cleaning up on this, but
> that's how it works for now, anyway. [And it does actually work, last I
> tested it :-)]

I looked into this and as is so frequently the case, we're both right. :-)

When running according to docs, that is with:
1. meson setup doc_build
2. ninja -C doc_build doc

it doesn't matter what enable_docs is set to, it always builds the docs.

But in the full build it does control whether docs are built, i.e.:

1. meson setup doc_build
2. ninja -C doc_build
doesn't build the docs, whereas:

1. meson setup doc_build -Denable_docs=true
2. ninja -C doc_build
builds the docs.

Now the problem in this version is when doing just the doc build
(ninja -C doc_build doc) both DPDK and DTS docs are built and I'd like
to separate those (because DTS doc build has additional dependencies).
I'm thinking the following would be a good solution within the current
paradigm:
1. The -Denable_docs=true and -Denable_dts_docs=true options to
separate doc builds for the full build.
2. Separate dts doc dir for the doc build ("ninja -C doc_build doc"
for DPDK docs and "ninja -C doc_build dts" (or maybe some other dir)
for DTS docs).

What do you think?
Juraj

>
> /Bruce
  

On Tue, Apr 25, 2023 at 10:20:36AM +0200, Juraj Linkeš wrote:
> On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote:
> > >    Hi Bruce, Thomas,
> > >    The meson integration is kinda all over the place. I wanted to use the
> > >    existing conf.py Sphinx config file, but I also wanted to keep the docs
> > >    separated (because of extra DTS api docs dependencies), so the various
> > >    pieces are in different places (the config file in one place, meson
> > >    code in dts directory and generated Sphinx docs are in a new directory
> > >    in the api build dir, separate from the rest of the Sphinx html).
> > >    The big thing here is that I didn't figure out how to separate the dts
> > >    api build from the rest of the docs. I don't know how the -Denable_docs
> > >    option is supposed to work. I wanted to use -Denable_dts_docs in the
> > >    same fashion to decouple the builds, but it doesn't seem to work.
> > >    Reading the code I think the original option doesn't actually do
> > >    anything - does it work? How is it supposed to work?
> > >    Thanks,
> > >    Juraj
> >
> > The enable_docs option works by selectively enabling the doc build tasks
> > using the "build_by_default" parameter on them.
> > See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an
> > example. The custom_target for sphinx is not a dependency of any other
> > task, so whether it gets run or not depends entirely on whether the
> > "build_by_default" and/or "install" options are set.
> >
> > As usual, there may be other stuff that needs cleaning up on this, but
> > that's how it works for now, anyway. [And it does actually work, last I
> > tested it :-)]
> 
> I looked into this and as is so frequently the case, we're both right. :-)
> 
> When running according to docs, that is with:
> 1. meson setup doc_build
> 2. ninja -C doc_build doc
> 
> it doesn't matter what enable_docs is set to, it always builds the docs.
> 

Yes, I'd forgotten that. That was deliberately done so one could always
request a doc build directly, without having to worry about DPDK config or
building the rest of DPDK.

> But in the full build it does control whether docs are built, i.e.:
> 
> 1. meson setup doc_build
> 2. ninja -C doc_build
> doesn't build the docs, whereas:
> 
> 1. meson setup doc_build -Denable_docs=true
> 2. ninja -C doc_build
> builds the docs.
> 
> Now the problem in this version is when doing just the doc build
> (ninja -C doc_build doc) both DPDK and DTS docs are built and I'd like
> to separate those (because DTS doc build has additional dependencies).
> I'm thinking the following would be a good solution within the current
> paradigm:
> 1. The -Denable_docs=true and -Denable_dts_docs=true options to
> separate doc builds for the full build.
> 2. Separate dts doc dir for the doc build ("ninja -C doc_build doc"
> for DPDK docs and "ninja -C doc_build dts" (or maybe some other dir)
> for DTS docs).

How important is it to separate out the dts docs from the regular docs?
What are the additional dependencies, and how hard are they to get? If
possible I'd rather not have an additional build config option added for
this.

If we are separating them out, I think the dts doc target should be
"dts_doc" rather than "dts" for clarity.

/Bruce
  

On Tue, Apr 25, 2023 at 10:44 AM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Tue, Apr 25, 2023 at 10:20:36AM +0200, Juraj Linkeš wrote:
> > On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson
> > <bruce.richardson@intel.com> wrote:
> > >
> > > On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote:
> > > >    Hi Bruce, Thomas,
> > > >    The meson integration is kinda all over the place. I wanted to use the
> > > >    existing conf.py Sphinx config file, but I also wanted to keep the docs
> > > >    separated (because of extra DTS api docs dependencies), so the various
> > > >    pieces are in different places (the config file in one place, meson
> > > >    code in dts directory and generated Sphinx docs are in a new directory
> > > >    in the api build dir, separate from the rest of the Sphinx html).
> > > >    The big thing here is that I didn't figure out how to separate the dts
> > > >    api build from the rest of the docs. I don't know how the -Denable_docs
> > > >    option is supposed to work. I wanted to use -Denable_dts_docs in the
> > > >    same fashion to decouple the builds, but it doesn't seem to work.
> > > >    Reading the code I think the original option doesn't actually do
> > > >    anything - does it work? How is it supposed to work?
> > > >    Thanks,
> > > >    Juraj
> > >
> > > The enable_docs option works by selectively enabling the doc build tasks
> > > using the "build_by_default" parameter on them.
> > > See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an
> > > example. The custom_target for sphinx is not a dependency of any other
> > > task, so whether it gets run or not depends entirely on whether the
> > > "build_by_default" and/or "install" options are set.
> > >
> > > As usual, there may be other stuff that needs cleaning up on this, but
> > > that's how it works for now, anyway. [And it does actually work, last I
> > > tested it :-)]
> >
> > I looked into this and as is so frequently the case, we're both right. :-)
> >
> > When running according to docs, that is with:
> > 1. meson setup doc_build
> > 2. ninja -C doc_build doc
> >
> > it doesn't matter what enable_docs is set to, it always builds the docs.
> >
>
> Yes, I'd forgotten that. That was deliberately done so one could always
> request a doc build directly, without having to worry about DPDK config or
> building the rest of DPDK.
>
> > But in the full build it does control whether docs are built, i.e.:
> >
> > 1. meson setup doc_build
> > 2. ninja -C doc_build
> > doesn't build the docs, whereas:
> >
> > 1. meson setup doc_build -Denable_docs=true
> > 2. ninja -C doc_build
> > builds the docs.
> >
> > Now the problem in this version is when doing just the doc build
> > (ninja -C doc_build doc) both DPDK and DTS docs are built and I'd like
> > to separate those (because DTS doc build has additional dependencies).
> > I'm thinking the following would be a good solution within the current
> > paradigm:
> > 1. The -Denable_docs=true and -Denable_dts_docs=true options to
> > separate doc builds for the full build.
> > 2. Separate dts doc dir for the doc build ("ninja -C doc_build doc"
> > for DPDK docs and "ninja -C doc_build dts" (or maybe some other dir)
> > for DTS docs).
>
> How important is it to separate out the dts docs from the regular docs?

It is mostly a matter of dependencies.

> What are the additional dependencies, and how hard are they to get? If
> possible I'd rather not have an additional build config option added for
> this.

The same dependencies as for running DTS, which are the proper Python
version (3.10 and newer) with DTS depencies obtained with Poetry
(which is a matter of installing Poetry and running it). As is
standard with Python projects, this is all set up in a virtual
environment, which needs to be activated before running the doc build.
It's documented in more detail in the tools docs:
https://doc.dpdk.org/guides/tools/dts.html#setting-up-dts-environment

This may be too much of a hassle for DPDK devs to build non-DTS docs,
but I don't know whether DPDK devs actually build docs at all.

>
> If we are separating them out, I think the dts doc target should be
> "dts_doc" rather than "dts" for clarity.

Agreed, but "dts_doc" would be a new top-level dir. I think we could
do dts/doc (a dir inside dts).

Juraj

>
> /Bruce
>
  

On Tue, Apr 25, 2023 at 10:57:12AM +0200, Juraj Linkeš wrote:
> On Tue, Apr 25, 2023 at 10:44 AM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > On Tue, Apr 25, 2023 at 10:20:36AM +0200, Juraj Linkeš wrote:
> > > On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson
> > > <bruce.richardson@intel.com> wrote:
> > > >
> > > > On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote:
> > > > >    Hi Bruce, Thomas,
> > > > >    The meson integration is kinda all over the place. I wanted to use the
> > > > >    existing conf.py Sphinx config file, but I also wanted to keep the docs
> > > > >    separated (because of extra DTS api docs dependencies), so the various
> > > > >    pieces are in different places (the config file in one place, meson
> > > > >    code in dts directory and generated Sphinx docs are in a new directory
> > > > >    in the api build dir, separate from the rest of the Sphinx html).
> > > > >    The big thing here is that I didn't figure out how to separate the dts
> > > > >    api build from the rest of the docs. I don't know how the -Denable_docs
> > > > >    option is supposed to work. I wanted to use -Denable_dts_docs in the
> > > > >    same fashion to decouple the builds, but it doesn't seem to work.
> > > > >    Reading the code I think the original option doesn't actually do
> > > > >    anything - does it work? How is it supposed to work?
> > > > >    Thanks,
> > > > >    Juraj
> > > >
> > > > The enable_docs option works by selectively enabling the doc build tasks
> > > > using the "build_by_default" parameter on them.
> > > > See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an
> > > > example. The custom_target for sphinx is not a dependency of any other
> > > > task, so whether it gets run or not depends entirely on whether the
> > > > "build_by_default" and/or "install" options are set.
> > > >
> > > > As usual, there may be other stuff that needs cleaning up on this, but
> > > > that's how it works for now, anyway. [And it does actually work, last I
> > > > tested it :-)]
> > >
> > > I looked into this and as is so frequently the case, we're both right. :-)
> > >
> > > When running according to docs, that is with:
> > > 1. meson setup doc_build
> > > 2. ninja -C doc_build doc
> > >
> > > it doesn't matter what enable_docs is set to, it always builds the docs.
> > >
> >
> > Yes, I'd forgotten that. That was deliberately done so one could always
> > request a doc build directly, without having to worry about DPDK config or
> > building the rest of DPDK.
> >
> > > But in the full build it does control whether docs are built, i.e.:
> > >
> > > 1. meson setup doc_build
> > > 2. ninja -C doc_build
> > > doesn't build the docs, whereas:
> > >
> > > 1. meson setup doc_build -Denable_docs=true
> > > 2. ninja -C doc_build
> > > builds the docs.
> > >
> > > Now the problem in this version is when doing just the doc build
> > > (ninja -C doc_build doc) both DPDK and DTS docs are built and I'd like
> > > to separate those (because DTS doc build has additional dependencies).
> > > I'm thinking the following would be a good solution within the current
> > > paradigm:
> > > 1. The -Denable_docs=true and -Denable_dts_docs=true options to
> > > separate doc builds for the full build.
> > > 2. Separate dts doc dir for the doc build ("ninja -C doc_build doc"
> > > for DPDK docs and "ninja -C doc_build dts" (or maybe some other dir)
> > > for DTS docs).
> >
> > How important is it to separate out the dts docs from the regular docs?
> 
> It is mostly a matter of dependencies.
> 
> > What are the additional dependencies, and how hard are they to get? If
> > possible I'd rather not have an additional build config option added for
> > this.
> 
> The same dependencies as for running DTS, which are the proper Python
> version (3.10 and newer) with DTS depencies obtained with Poetry
> (which is a matter of installing Poetry and running it). As is
> standard with Python projects, this is all set up in a virtual
> environment, which needs to be activated before running the doc build.
> It's documented in more detail in the tools docs:
> https://doc.dpdk.org/guides/tools/dts.html#setting-up-dts-environment
> 
> This may be too much of a hassle for DPDK devs to build non-DTS docs,
> but I don't know whether DPDK devs actually build docs at all.
> 

Can't really say for sure. I suspect most don't build them on a daily
basis, but would often need to build them before submitting patches with a
doc change included.

What format are the DTS docs in? I agree that as described above the
requirements are pretty different than those for the regular DPDK docs.

> >
> > If we are separating them out, I think the dts doc target should be
> > "dts_doc" rather than "dts" for clarity.
> 
> Agreed, but "dts_doc" would be a new top-level dir. I think we could
> do dts/doc (a dir inside dts).
> 
That path seems reasonable to me.

/Bruce
  

On Tue, Apr 25, 2023 at 11:43 AM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Tue, Apr 25, 2023 at 10:57:12AM +0200, Juraj Linkeš wrote:
> > On Tue, Apr 25, 2023 at 10:44 AM Bruce Richardson
> > <bruce.richardson@intel.com> wrote:
> > >
> > > On Tue, Apr 25, 2023 at 10:20:36AM +0200, Juraj Linkeš wrote:
> > > > On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson
> > > > <bruce.richardson@intel.com> wrote:
> > > > >
> > > > > On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote:
> > > > > >    Hi Bruce, Thomas,
> > > > > >    The meson integration is kinda all over the place. I wanted to use the
> > > > > >    existing conf.py Sphinx config file, but I also wanted to keep the docs
> > > > > >    separated (because of extra DTS api docs dependencies), so the various
> > > > > >    pieces are in different places (the config file in one place, meson
> > > > > >    code in dts directory and generated Sphinx docs are in a new directory
> > > > > >    in the api build dir, separate from the rest of the Sphinx html).
> > > > > >    The big thing here is that I didn't figure out how to separate the dts
> > > > > >    api build from the rest of the docs. I don't know how the -Denable_docs
> > > > > >    option is supposed to work. I wanted to use -Denable_dts_docs in the
> > > > > >    same fashion to decouple the builds, but it doesn't seem to work.
> > > > > >    Reading the code I think the original option doesn't actually do
> > > > > >    anything - does it work? How is it supposed to work?
> > > > > >    Thanks,
> > > > > >    Juraj
> > > > >
> > > > > The enable_docs option works by selectively enabling the doc build tasks
> > > > > using the "build_by_default" parameter on them.
> > > > > See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an
> > > > > example. The custom_target for sphinx is not a dependency of any other
> > > > > task, so whether it gets run or not depends entirely on whether the
> > > > > "build_by_default" and/or "install" options are set.
> > > > >
> > > > > As usual, there may be other stuff that needs cleaning up on this, but
> > > > > that's how it works for now, anyway. [And it does actually work, last I
> > > > > tested it :-)]
> > > >
> > > > I looked into this and as is so frequently the case, we're both right. :-)
> > > >
> > > > When running according to docs, that is with:
> > > > 1. meson setup doc_build
> > > > 2. ninja -C doc_build doc
> > > >
> > > > it doesn't matter what enable_docs is set to, it always builds the docs.
> > > >
> > >
> > > Yes, I'd forgotten that. That was deliberately done so one could always
> > > request a doc build directly, without having to worry about DPDK config or
> > > building the rest of DPDK.
> > >
> > > > But in the full build it does control whether docs are built, i.e.:
> > > >
> > > > 1. meson setup doc_build
> > > > 2. ninja -C doc_build
> > > > doesn't build the docs, whereas:
> > > >
> > > > 1. meson setup doc_build -Denable_docs=true
> > > > 2. ninja -C doc_build
> > > > builds the docs.
> > > >
> > > > Now the problem in this version is when doing just the doc build
> > > > (ninja -C doc_build doc) both DPDK and DTS docs are built and I'd like
> > > > to separate those (because DTS doc build has additional dependencies).
> > > > I'm thinking the following would be a good solution within the current
> > > > paradigm:
> > > > 1. The -Denable_docs=true and -Denable_dts_docs=true options to
> > > > separate doc builds for the full build.
> > > > 2. Separate dts doc dir for the doc build ("ninja -C doc_build doc"
> > > > for DPDK docs and "ninja -C doc_build dts" (or maybe some other dir)
> > > > for DTS docs).
> > >
> > > How important is it to separate out the dts docs from the regular docs?
> >
> > It is mostly a matter of dependencies.
> >
> > > What are the additional dependencies, and how hard are they to get? If
> > > possible I'd rather not have an additional build config option added for
> > > this.
> >
> > The same dependencies as for running DTS, which are the proper Python
> > version (3.10 and newer) with DTS depencies obtained with Poetry
> > (which is a matter of installing Poetry and running it). As is
> > standard with Python projects, this is all set up in a virtual
> > environment, which needs to be activated before running the doc build.
> > It's documented in more detail in the tools docs:
> > https://doc.dpdk.org/guides/tools/dts.html#setting-up-dts-environment
> >
> > This may be too much of a hassle for DPDK devs to build non-DTS docs,
> > but I don't know whether DPDK devs actually build docs at all.
> >
>
> Can't really say for sure. I suspect most don't build them on a daily
> basis, but would often need to build them before submitting patches with a
> doc change included.
>
> What format are the DTS docs in? I agree that as described above the
> requirements are pretty different than those for the regular DPDK docs.
>

The resulting html docs are using the same Sphinx conf file (with
extension configuration and two more config options - see patch 3/4)
as we're using for regular docs.

> > >
> > > If we are separating them out, I think the dts doc target should be
> > > "dts_doc" rather than "dts" for clarity.
> >
> > Agreed, but "dts_doc" would be a new top-level dir. I think we could
> > do dts/doc (a dir inside dts).
> >
> That path seems reasonable to me.
>
> /Bruce