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 0294945711;
	Thu,  1 Aug 2024 17:07:42 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id D3C1B40E24;
	Thu,  1 Aug 2024 17:07:41 +0200 (CEST)
Received: from fhigh5-smtp.messagingengine.com
 (fhigh5-smtp.messagingengine.com [103.168.172.156])
 by mails.dpdk.org (Postfix) with ESMTP id 7712D40BA2
 for <dev@dpdk.org>; Thu,  1 Aug 2024 17:07:40 +0200 (CEST)
Received: from compute4.internal (compute4.nyi.internal [10.202.2.44])
 by mailfhigh.nyi.internal (Postfix) with ESMTP id E7968114745E;
 Thu,  1 Aug 2024 11:07:39 -0400 (EDT)
Received: from mailfrontend2 ([10.202.2.163])
 by compute4.internal (MEProxy); Thu, 01 Aug 2024 11:07:39 -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=1722524859;
 x=1722611259; bh=xkno5Z33BzLapL/tXzqhTFGs/AgbI0nNuR42w/zY0DY=; b=
 GI1xKPiHtVcQRcFE0BFlcs4UkKJmAbtSBhv+KFTwxA4/E4pqhXVSBNcLzaQhMF/p
 KCX0ttNq9azpShmM8fMdT1pvZc7gUTkrv75MOHMjoScsgzWEthVXrf4c/CVhy2+F
 ue/WzxTpaa4rMkCENTQIws1agEsABmCvN4XuVm900ehkOkVLpAlaYmAmuOdexOuy
 tMbuSRSEJjwdWBuRubaI7nj/z5CkCiNDryfvS115S4B6hPVcy8qPHsOIu9GlYhgA
 nI5r6jwBs+gOT35g6N48PdOS2DqSu9c9visFD7cqeBul2RJEvFILWvkcMD5IQX0+
 OGnoL7VV2QsUYlWtt8KHOg==
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=1722524859; x=
 1722611259; bh=xkno5Z33BzLapL/tXzqhTFGs/AgbI0nNuR42w/zY0DY=; b=U
 WyDQ6YBQvDxtZuq/iWKUtrrlbHzHFrb903oVuF7EppJWPaikYz/hNQJhINuCvFJG
 KxKP7Qk5lADkOEeNBbhAXwXjmY+wEFVhGd/1acX5XW3tci7o1z7C+0WKi4aBvguh
 FXFVkQ6yrkmLNKfv+Qj0GtkyOq1WbFlOfQAMJ9Lx5ZG7YgLNb8h36pw153GxYDGa
 EVmyzRuuuto751uFqhOe+qqWu2Nhqz1HmCnBvvHZ7r7mGXUAaZ58tK6RC6kt9IcC
 sl2FbzwWTpeGSU/NAvE9qgKFcEQZUP1lxdiFcdiO+nLHnKj+5kK/VcpQjg2ctEnE
 uQ03gekdDDu1gIdInlLUQ==
X-ME-Sender: <xms:uqSrZuHFFyrB9L7ub8jap3bfrIh8zh75SmTSIVRrJwMBN0p8iJc1Jg>
 <xme:uqSrZvWCSRlztMcFjAX3D0-f6Pwyn4dvPp4pwnmHTpSCAPg7c0XIHl4NtYpvcjF9o
 q2TfPwvcA1iahoQBw>
X-ME-Received: <xmr:uqSrZoI4MffWTIU_vJvhaP5hTF4yvUhpoiS_vwALR_EAlni4kzmT0AteZeTGdnrxqY580DBRNxI9oqyVy5uzmC43Ig>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeekgdekhecutefuodetggdotefrodftvf
 curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu
 uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc
 fjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdejnecuhfhrohhmpefvhhhomhgr
 shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg
 ftrfgrthhtvghrnhepgedttdeljeejgeffkeekkedtjeevtdehvedtkeeivdeuuedviedu
 vdelveejueejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh
 homhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvthdpnhgspghrtghpthhtoheptd
X-ME-Proxy: <xmx:u6SrZoFHdZHIeo2l0kzN1D-VLMfyKvTSyvTFLdbIl2S8ComHOaVEYA>
 <xmx:u6SrZkUcXVI2FWdPoHglRpYgO-RLeqcrhh9rfCGYktW7icC2JT-4pQ>
 <xmx:u6SrZrOjjR9EobukjzvVLH4Ei7utq-aEhpTrKqd387pLzU57xa-KQw>
 <xmx:u6SrZr0WA0aEtRkxxesYT7IweDxf5qoTdKxlyb6-ZiwGYi3QvrB7yQ>
 <xmx:u6SrZtNJh-OP6GHDCgMKJg9-52-QM_PCFEIPUcFVkpqs4txnMneeZRMA>
Feedback-ID: i47234305:Fastmail
Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu,
 1 Aug 2024 11:07:37 -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,
 bruce.richardson@intel.com
Subject: Re: [PATCH v8 5/5] dts: add API doc generation
Date: Thu, 01 Aug 2024 17:07:35 +0200
Message-ID: <2336017.ElGaqSPkdT@thomas>
In-Reply-To: <9cfefccb-0190-46d3-8942-c8c82da38f99@pantheon.tech>
References: <20231115133606.42081-1-juraj.linkes@pantheon.tech>
 <10378083.0AQdONaE2F@thomas>
 <9cfefccb-0190-46d3-8942-c8c82da38f99@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

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:
> >> The tool used to generate DTS API docs is Sphinx, which is already in
> >> use in DPDK. The same configuration is used to preserve style with one
> >> DTS-specific configuration (so that the DPDK docs are unchanged) that
> >> modifies how the sidebar displays the content.
> >=20
> > What is changed in the sidebar?
> >=20
>=20
> These are the two changes:
> html_theme_options =3D {
>      'collapse_navigation': False,
>      'navigation_depth': -1,
> }
>=20
> The first allows you to explore the structure without needing to enter=20
> any specific section - it puts the + at each section so everything is=20
> expandable.
> The second just means that each section can be fully expanded (there's=20
> no limit).

OK interesting, you may add a comment # unlimited depth


> >> +# A local reference must be relative to the main index.html page
> >> +# The path below can't be taken from the DTS meson file as that would
> >> +# require recursive subdir traversal (doc, dts, then doc again)
> >=20
> > This comment is really obscure.
>=20
> I guess it is. I just wanted to explain that there's not way to do this=20
> without spelling out the path this way. At least I didn't find a way.
> Should I remove the comment or reword it?

May be removed I think.

> >> +cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index=
=2Ehtml'))
> >=20
> > Oh I think I get it:
> > 	- DTS_API_MAIN_PAGE is the Meson variable
> > 	- dts_api_main_page is the Doxygen variable
> >=20
>=20
> Yes, this is a way to make it work. Maybe there's something else (I'm=20
> not that familiar with Doxygen), but from what I can tell, there wasn't=20
> a command line option that would set a variable (passing the path form=20
> Meson to Doxygen) and nothing else I found worked.
>=20
> Is this solution ok? If we want to explore something else, is there=20
> someone with more experience with Doxygen who could help?

Yes it's OK like that.


> >> +dts_root =3D environ.get('DTS_ROOT')
> >=20
> > Why does it need to be passed as an environment variable?
> > Isn't it a fixed absolute path?
>=20
> The path to DTS needs to be passed in some way (and added to sys.path)=20
> so that Sphinx knows where the sources are in order to import them.
>=20
> Do you want us to not pass the path, but just hardcode it here? I didn't=
=20
> really think about that, maybe that could work.

I think hardcode is better here.


> >> +To build DTS API docs, install the dependencies with Poetry, then ent=
er its shell:
> >=20
> > I don't plan to use Poetry on my machine.
> > Can we simply describe the dependencies even if the versions are not sp=
ecified?
>=20
> The reason we don't list the dependencies anywhere is that doing it with=
=20
> Poetry is much easier (and a bit safer, as Poetry is going to install=20
> tested versions).
>=20
> But I can add references to the two relevant sections of=20
> dts/pyproject.toml which contain the dependencies with a note that they=20
> can be installed with pip (and I guess that would be another=20
> dependency), but at that point it's that not much different than using=20
> Poetry.

I want to use my system package manager.
I am from this old school thinking we should have a single package manager =
in a system.

> >> +.. 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, build =
the documentation with:
> >> +
> >> +.. code-block:: console
> >> +
> >> +   ninja -C build dts-doc
> >=20
> > Don't we rely on the Meson option "enable_docs"?
>=20
> I had a discussion about this with Bruce, but I can't find it anywhere,=20
> so here's what I remember:
> 1. We didn't want to tie the dts api doc build to dpdk doc build because=
=20
> of the dependencies.

Sure
But we could just skip if dependencies are not met?

> 2. There's a way to build docs without the enable_docs option (running=20
> ninja with the target), which is what we added for dts. This doesn't tie=
=20
> the dts api doc build to the dpdk doc build.

Yes

> 3. We had an "enable_dts_docs" Meson option in the past (to keep it=20
> separate from dpdk doc build), but decided to drop it. My memory is hazy=
=20
> on this, but I think it was, again, because of the additional steps=20
> needed to bring up the dependency (poetry shell) - at that point,=20
> supporting just the ninja build way is sufficient. Bruce may shed more=20
> light on this.


> >> +   Make sure to fix any Sphinx warnings when adding or updating docst=
rings,
> >> +   and also run the ``devtools/dts-check-format.sh`` script and addre=
ss any issues it finds.
> >=20
> > It looks like something to write in the contributing guide.
> >=20
>=20
> I could add it there, where is the right place? In patches.rst, section=20
> "Checking the Patches"?

Yes