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 3D74A429E9; Tue, 25 Apr 2023 10:57:25 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C91E1410EA; Tue, 25 Apr 2023 10:57:24 +0200 (CEST) Received: from mail-ed1-f47.google.com (mail-ed1-f47.google.com [209.85.208.47]) by mails.dpdk.org (Postfix) with ESMTP id 58736410DD for ; Tue, 25 Apr 2023 10:57:24 +0200 (CEST) Received: by mail-ed1-f47.google.com with SMTP id 4fb4d7f45d1cf-5068e99960fso9470610a12.1 for ; Tue, 25 Apr 2023 01:57:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1682413044; x=1685005044; 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=QV9t9d+QBX+VrRddMEH70JtfkHFI/vZp+f4jIpHGXyQ=; b=D6L7qkErZPerGQKn+MKJoC1zvX5qJuV0aNKwiv4GCaSesdIskAyhKSzVtnxR0kiZ0p OKOP5UY1AbIRxX28sGbtoH5LotygK9G/1pB6qCB94iSbrJcxhPulytSHy8eDbjmuMgR1 3qCQAqafwFr4H1Zbd19BtWyIrHuAFeTfY346YnWfois2b4bhC8hz62i3HL7tsvsoXtBD UE2KKTmnEorNWYtYvpIUk3UeP2Ih+0yb2sls6+OGsBHgnJTaezGy0SVpsTq0uRMGsO2a cc3tgRgbmBgeHRsAdeV1RkAqOPSSwR1/ol9j8ca+S9pw2rbjqRJsLJEGOrubhq1rxbKW F4RQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682413044; x=1685005044; 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=QV9t9d+QBX+VrRddMEH70JtfkHFI/vZp+f4jIpHGXyQ=; b=KXrK8PSjzmk8ju3Cr5GQ1dvS1ei6d0qXR+Dwl60ZNNFRc0vWNm9RZFj6vuzcY14NLp AJPzYx6O26vZUxFKh2QpJjZCSlc9oh6sCkdjmMV0ZHn/W0gxsSL/sjx+OYniqbhXGgCX J9MDqe9u51Yf1GsZiaH0WH+NBMyCkJM6YNMY4IwKsYKaNU4IWb+njlkC2O7JD3LgGX6L BaParzUDRyV3rd80TAcAiWxx429zKeI7AYPKy5nbwJjE4LRGYJcvf+UFrhL0ynfLpYJj OEabkIr4p9TIJb8puaiAmevN4mpqBKacwNbPA7rM36KlflAWd+3UOoIuhsKiSEN6cv15 0MOA== X-Gm-Message-State: AAQBX9cB7ty8/dc5uw1bsssFRKaP8C0Cu61aU9DMt3Cu79TCWfWWIHQa diAglbzofYzqlE4AmB1A20Urd/wsr+IBdQXYm3M8bd4j9zASZE87kGxl4qVdWZGfug1MUdpCqCH xajt6a1ma4DuWvw== X-Google-Smtp-Source: AKy350a2ZDlPP6OsyX3DpMZdBmC4AUNqcUFXXafemJtsicgCMEvEJA3UjpR1CNvTFr5VbQDX7rVlkTJ4LBQDkUPG9/U= X-Received: by 2002:a05:6402:146:b0:506:75d4:44 with SMTP id s6-20020a056402014600b0050675d40044mr12948037edu.25.1682413043801; Tue, 25 Apr 2023 01:57:23 -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: Tue, 25 Apr 2023 10:57:12 +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 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 u= se the > > > > existing conf.py Sphinx config file, but I also wanted to keep t= he docs > > > > separated (because of extra DTS api docs dependencies), so the v= arious > > > > pieces are in different places (the config file in one place, me= son > > > > code in dts directory and generated Sphinx docs are in a new dir= ectory > > > > 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 t= he dts > > > > api build from the rest of the docs. I don't know how the -Denab= le_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 ta= sks > > > 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 othe= r > > > 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, bu= t > > > 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 o= r > 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 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=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 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 >