On Tue, Apr 25, 2023 at 11:43 AM Bruce Richardson <bruce.richard...@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.richard...@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.richard...@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
