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

["Juraj Linkeš" <juraj.linkes@pantheon.tech>]

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