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

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

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