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 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 ; 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: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeekgdekhecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdejnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepgedttdeljeejgeffkeekkedtjeevtdehvedtkeeivdeuuedviedu vdelveejueejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh homhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvthdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i47234305:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu, 1 Aug 2024 11:07:37 -0400 (EDT) From: Thomas Monjalon To: Juraj =?utf-8?B?TGlua2XFoQ==?= 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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