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. > > > > 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
