From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id BFB1D4571A;
Fri, 2 Aug 2024 15:53:10 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 9147941141;
Fri, 2 Aug 2024 15:53:10 +0200 (CEST)
Received: from fout6-smtp.messagingengine.com (fout6-smtp.messagingengine.com
[103.168.172.149])
by mails.dpdk.org (Postfix) with ESMTP id 77B8F40E20
for <dev@dpdk.org>; Fri, 2 Aug 2024 15:53:09 +0200 (CEST)
Received: from compute5.internal (compute5.nyi.internal [10.202.2.45])
by mailfout.nyi.internal (Postfix) with ESMTP id 24FD0138543E;
Fri, 2 Aug 2024 09:53:09 -0400 (EDT)
Received: from mailfrontend1 ([10.202.2.162])
by compute5.internal (MEProxy); Fri, 02 Aug 2024 09:53:09 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h=
cc:cc:content-transfer-encoding:content-type:content-type:date
:date:from:from:in-reply-to:in-reply-to:message-id:mime-version
:references:reply-to:subject:subject:to:to; s=fm3; t=1722606789;
x=1722693189; bh=HmUdA22vrRahvOve5tcOUlX2sOYjhL8GUfxwF/Mt4k8=; b=
UWdO80Tr9uhLLCa+m3hLK1Z7MxLwRsaaryRHigVw+LlHOgaUQ6Q5+/tATlBg094O
LCNKqllpxCZMMxTRW9LnoODf988ugHSAWA4R9E9PtgqB3vce5H4+Ju6GvQsCgLrN
tlXFYpWE7SvBAKZ9HQkCbHGJCCTtZ9gTxiGy5QhVCDglmQkmaGJJdMJcyLCB+Lku
YUwHQ2F6Sw+UTS7yFANTrmo98/VpTG2I5TWGkHWL0PP75ENWA1zQa2klnswoqbdT
56DsgEs3LFJSAmG2yzvaFlewsqfTRkREcJ38TSKOO8hURU1hIkDP3jgj7XiIqumy
Ng8KNW6pI0jlW6ATMKhr4A==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=
messagingengine.com; h=cc:cc:content-transfer-encoding
:content-type:content-type:date:date:feedback-id:feedback-id
:from:from:in-reply-to:in-reply-to:message-id:mime-version
:references:reply-to:subject:subject:to:to:x-me-proxy:x-me-proxy
:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t=1722606789; x=
1722693189; bh=HmUdA22vrRahvOve5tcOUlX2sOYjhL8GUfxwF/Mt4k8=; b=b
YMXVrEy0SS7OsuBazooQ2CBgONWUCUB5cKvAWiYD7colD+H6eJPOsVVwcpzFmKw+
XPKpBF/aoPn5VCeNxwvhqFiCZJSDjXd2jvnWY1cguYHtcDowypJECqDf7hPajUvx
ZMPJDzhwWEFomlr3nfAWISH0UpkL9PRx1HAVKPsBIjA7lKZFMXGAo0SAoJQaOl2J
pd7HxvOR+BzbVFO4UHvIhAui1QbbXSE6lCsg3aSs8ZTZsCSerf+qU8bCLUChfEeZ
IxL2jq/roU9e78gRO+WD0f3lb0GgtXC5Ih4Jd2VZ1OaAwfvv7SdRLVT+xXny5a35
/xgeJLbvrugtpJ3gEC1vg==
X-ME-Sender: <xms:xOSsZp0rd-Lhs7OM-UUIIbJtOT8rbE5k3A_rO0OX0x0dCwKOZwW4ng>
<xme:xOSsZgG8niA_pnuI_hNNK8Lq3hGJn8eao-vsMQYY1MRk9hBAB-SJ538dn7vcSC3BB
wiaIdJ4Lo0bqpla7Q>
X-ME-Received: <xmr:xOSsZp5Ky6YS7J2yPMylLISBwsOLvdyDBjL6N-z1seX79m0Ls-KIyfp5PRssPk8EHq96Hma8eCpgzArH3Kdk0YvGMA>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrkedtgdeilecutefuodetggdotefrodftvf
curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu
uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc
fjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdejnecuhfhrohhmpefvhhhomhgr
shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg
ftrfgrthhtvghrnhepgedttdeljeejgeffkeekkedtjeevtdehvedtkeeivdeuuedviedu
vdelveejueejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh
homhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvthdpnhgspghrtghpthhtoheptd
X-ME-Proxy: <xmx:xOSsZm0lJLxYoi94Wo4-mACetMDLM8-va4lpzRbZ9BszR_qQSy2r9A>
<xmx:xOSsZsGhw9dO-ocl5fUhsSIg0enUon2RnzlkzE4A4tovXnhGaROiKA>
<xmx:xOSsZn_hcZ4dsELEkCJtFz5TwbN5x3_Fl_drxVgEm_zaKd_WCoOjlQ>
<xmx:xOSsZpmuxjwlT-lue89TGfM-U1TosbphqMPmVnW1xe5-7etBkJk_Ew>
<xmx:xeSsZnB78f_PpFZ0u57Dwg3_oUlCuhd7XYKeeC4XXFU75zoMWcEHXJ9Y>
Feedback-ID: i47234305:Fastmail
Received: by mail.messagingengine.com (Postfix) with ESMTPA; Fri,
2 Aug 2024 09:53:07 -0400 (EDT)
From: Thomas Monjalon <thomas@monjalon.net>
To: Juraj =?utf-8?B?TGlua2XFoQ==?= <juraj.linkes@pantheon.tech>
Cc: Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com,
jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com,
Luca.Vizzarro@arm.com, npratte@iol.unh.edu, dev@dpdk.org
Subject: Re: [PATCH v8 5/5] dts: add API doc generation
Date: Fri, 02 Aug 2024 15:53:06 +0200
Message-ID: <1801384.VLH7GnMWUR@thomas>
In-Reply-To: <5322c7b0-4935-439b-b8d5-a11bdac15150@pantheon.tech>
References: <20231115133606.42081-1-juraj.linkes@pantheon.tech>
<2336017.ElGaqSPkdT@thomas>
<5322c7b0-4935-439b-b8d5-a11bdac15150@pantheon.tech>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset="utf-8"
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
02=C3=A9 x/08/2024 12:48, Juraj Linke=C5=A1:
> On 1. 8. 2024 17:07, Thomas Monjalon wrote:
> > 01/08/2024 15:03, Juraj Linke=C5=A1:
> >> On 30. 7. 2024 15:51, Thomas Monjalon wrote:
> >>> 12/07/2024 10:57, Juraj Linke=C5=A1:
> >>>> +dts_root =3D environ.get('DTS_ROOT')
> >>>
> >>> Why does it need to be passed as an environment variable?
> >>> Isn't it a fixed absolute path?
> >>
> >> The path to DTS needs to be passed in some way (and added to sys.path)
> >> so that Sphinx knows where the sources are in order to import them.
> >>
> >> Do you want us to not pass the path, but just hardcode it here? I didn=
't
> >> really think about that, maybe that could work.
> >=20
> > I think hardcode is better here. xFalse,
> 'navigation_depth': -1,
> }
>=20
> The sidebar configuration is conditional, so we have to pass something=20
> to indicate dts build. I'll change it so that we look for 'dts' in src=20
> in call-sphinx-build.py (we're in the dts doc directory, indicating dts=20
> build) and set the DTS_BUILD env var which we can use in conf.py. I=20
> didn't find a better way to do this as conf.py doesn't have any=20
> information about the build itself (and no path that conf.py has access=20
> to points to anything dts). Here's how it'll look:
>=20
> if environ.get('DTS_BUILD'):
> path.append(path_join(dirname(dirname(dirname(__file__))), 'dts'))
> # DTS Sidebar config.
> html_theme_options =3D {
> 'collapse_navigation': False,
> 'navigation_depth': -1, # unlimited depth
> }
OK
> >>>> +To build DTS API docs, install the dependencies with Poetry, then e=
nter its shell:
> >>>
> >>> I don't plan to use Poetry on my machine.
> >>> Can we simply describe the dependencies even if the versions are not =
specified?
> >>
> >> The reason we don't list the dependencies anywhere is that doing it wi=
th
> >> Poetry is much easier (and a bit safer, as Poetry is going to install
> >> tested versions).
> >>
> >> But I can add references to the two relevant sections of
> >> dts/pyproject.toml which contain the dependencies with a note that they
> >> can be installed with pip (and I guess that would be another
> >> dependency), but at that point it's that not much different than using
> >> Poetry.
> >=20
> > I want to use my system package manager.
> > I am from this old school thinking we should have a single package mana=
ger in a system.
> >=20
>=20
> I understand and would also prefer that, but it just doesn't work for=20
> Python. Not all packages are available from the package managers, and=20
> Python projects should not use system packages as there are frequently=20
> version mismatches between the system packages and what the project=20
> needs (the APIs could be different as well as behavior; a problem we've=20
> seen with Scapy). Poetry is one of the tools that tries to solve this=20
> well-known Python limitation.
I fully agree for DTS runtime.
I'm expecting the dependencies are more tolerant for DTS doc.
> I've done a quick search of what's available in Ubuntu and two packages=20
> aren't available, types-PyYAML (which maybe we could do without, I'll=20
> have to test) and aenum (which is currently needed for the capabilities=20
> patch; if absolutely necessary, maybe I could find a solution without=20
> aenum). But even with this we can't be sure that the system package=20
> versions will work.
We need them all to generate the documentation?
> >>>> +.. code-block:: console
> >>>> +
> >>>> + poetry install --no-root --with docs
> >>>> + poetry shell
> >>>> +
> >>>> +The documentation is built using the standard DPDK build system.
> >>>> +After executing the meson command and entering Poetry's shell, buil=
d the documentation with:
> >>>> +
> >>>> +.. code-block:: console
> >>>> +
> >>>> + ninja -C build dts-doc
> >>>
> >>> Don't we rely on the Meson option "enable_docs"?
> >>
> >> I had a discussion about this with Bruce, but I can't find it anywhere,
> >> so here's what I remember:
> >> 1. We didn't want to tie the dts api doc build to dpdk doc build becau=
se
> >> of the dependencies.
> >=20
> > Sure
> > But we could just skip if dependencies are not met?
>=20
> Maybe we could add a script that would check the dependencies. I'll see=20
> what I can do.
OK thanks