From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 315CD42A4E; Wed, 3 May 2023 13:33:15 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 091934114B; Wed, 3 May 2023 13:33:15 +0200 (CEST) Received: from mail-ed1-f53.google.com (mail-ed1-f53.google.com [209.85.208.53]) by mails.dpdk.org (Postfix) with ESMTP id 7A83D41144 for ; Wed, 3 May 2023 13:33:13 +0200 (CEST) Received: by mail-ed1-f53.google.com with SMTP id 4fb4d7f45d1cf-50bc37e1525so7314188a12.1 for ; Wed, 03 May 2023 04:33:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683113593; x=1685705593; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=7B2JN57bnSYqJSGH41vOrrmApy4sAWeuNARVOXDT1qM=; b=G8CGcGd+MRDwXDO2GpCM7fbdjMUA9jb/LKuyFhvrJRSnO+Hqh7FoxZA6NjuXiQ71ow N+SsK7QSHi2+I9ixokbZowyMvWGmNQJKxLfebyX7kM2nS3ouQizx3Uw5KKidJdwX6Nrh W08glwye5Q4rvOcP31o7GEqzY6JG6QeHfWnEJQp2RpJp+YKCQgK8qNuvc+zbpKY4r33r v1czZeFVwWFsm0rDQ8i+u9/ruNcDcjCFzDwQFot5iNUguUoz6TmXaMePMIlivhRP+ZRQ b+cgWPjEqyw129GtoIV5lIm0t8R5TT6cgqUnqjxEiBzdkr57fUwoCVoi+453ALdGj6Ki KtuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683113593; x=1685705593; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=7B2JN57bnSYqJSGH41vOrrmApy4sAWeuNARVOXDT1qM=; b=kf0UoqXXs+qWxpnf/frBC5xUnWbSmq/njBkL2cjvrA3Z4mwasmXD5QdBwhXKRpzSCV DkuOGiF/YtJJMB4UMNCf2y9j2w2RIR52q3b+2t0fGsDyIVSSkakLVknFFPtERRnU6Out 9AefzQJCaclo/PdoYj8vVL/45OM18DYr6vNnwZCe+G0qNJG55gvwQsWbzBoWXN0x31uG /x/Wa7qke++5V3IpiAHtVVQ+Gmy6SVGrhJ1xEt98Ki+ZNII/m7DYXUB4b5dmPci5nPlL od7HRWoh9zf5klVk0Hvxe+yFVaugqTq2zvNZ3Peo4vI4QaTewbcytZk0ryUsvBSY8hpV iVhw== X-Gm-Message-State: AC+VfDzdxwiMYi3AL8iPrHUyDBd8LnPLsB9zJahKntytTcN7+932hukC eOz+cuyNdizFrmu6vaYGpbYmGuquRKYIAoaIK1IXXxlYKgNIHGw1 X-Google-Smtp-Source: ACHHUZ6ZtgTFgbfoZ0NfqJmKmH4bx9fCao9uWTiU/4LVf+SyI2pjeuu9o5Q0OQEL0J6ggetT0EOdlJHtkR62Mb9DQeU= X-Received: by 2002:aa7:cfd6:0:b0:506:7385:9653 with SMTP id r22-20020aa7cfd6000000b0050673859653mr10822271edy.39.1683113592984; Wed, 03 May 2023 04:33:12 -0700 (PDT) MIME-Version: 1.0 References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> In-Reply-To: From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Wed, 3 May 2023 13:33:01 +0200 Message-ID: Subject: Re: [RFC PATCH v1 0/4] dts: add dts api docs To: Bruce Richardson Cc: dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On Tue, Apr 25, 2023 at 11:43=E2=80=AFAM Bruce Richardson wrote: > > On Tue, Apr 25, 2023 at 10:57:12AM +0200, Juraj Linke=C5=A1 wrote: > > On Tue, Apr 25, 2023 at 10:44=E2=80=AFAM Bruce Richardson > > wrote: > > > > > > On Tue, Apr 25, 2023 at 10:20:36AM +0200, Juraj Linke=C5=A1 wrote: > > > > On Mon, Apr 3, 2023 at 11:42=E2=80=AFAM Bruce Richardson > > > > wrote: > > > > > > > > > > On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linke=C5=A1 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 ke= ep the docs > > > > > > separated (because of extra DTS api docs dependencies), so t= he 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 h= tml). > > > > > > The big thing here is that I didn't figure out how to separa= te the dts > > > > > > api build from the rest of the docs. I don't know how the -D= enable_docs > > > > > > option is supposed to work. I wanted to use -Denable_dts_doc= s 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 actuall= y do > > > > > > anything - does it work? How is it supposed to work? > > > > > > Thanks, > > > > > > Juraj > > > > > > > > > > The enable_docs option works by selectively enabling the doc buil= d 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 t= he > > > > > "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 rig= ht. :-) > > > > > > > > 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 alwa= ys > > > request a doc build directly, without having to worry about DPDK conf= ig 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=3Dtrue > > > > 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 l= ike > > > > to separate those (because DTS doc build has additional dependencie= s). > > > > I'm thinking the following would be a good solution within the curr= ent > > > > paradigm: > > > > 1. The -Denable_docs=3Dtrue and -Denable_dts_docs=3Dtrue 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 doc= s? > > > > It is mostly a matter of dependencies. > > > > > What are the additional dependencies, and how hard are they to get? I= f > > > 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