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

[Juraj Linkeš]

On Tue, Apr 25, 2023 at 10:44 AM Bruce Richardson
<bruce.richardson at 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 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.
> >
>
> 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
>