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

[Juraj Linkeš]

On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson
<bruce.richardson at 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