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 72CEC459AE; Mon, 16 Sep 2024 14:48:46 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F2DC14025F; Mon, 16 Sep 2024 14:48:45 +0200 (CEST) Received: from fhigh2-smtp.messagingengine.com (fhigh2-smtp.messagingengine.com [103.168.172.153]) by mails.dpdk.org (Postfix) with ESMTP id 1210A40150 for ; Mon, 16 Sep 2024 14:48:44 +0200 (CEST) Received: from phl-compute-07.internal (phl-compute-07.phl.internal [10.202.2.47]) by mailfhigh.phl.internal (Postfix) with ESMTP id 96D441140262; Mon, 16 Sep 2024 08:48:43 -0400 (EDT) Received: from phl-mailfrontend-02 ([10.202.2.163]) by phl-compute-07.internal (MEProxy); Mon, 16 Sep 2024 08:48:43 -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=fm1; t=1726490923; x=1726577323; bh=lpEUdO/wPpSPwPKrfTr4hfW9fI0zZIvGI75OarIuJAs=; b= OxyyWSI769NINZw4THSR1jgS5+fcMCnTUq3lkHQxOnZO8yBdN4+QvBacddzBcw7O E6jXNNgZiInFgk4qlRQyREMyqCd3W5AgKcFnKNXQbcxeODCkGcGd/N8BL8GX6lhB mZxewZVZEyehR+VwX6HVOMm+vbd/n5omqZkmWSSEDT8aayNMmSsbaa/vIIOIpsXu GIXGC/s+d5VxJLq+WgCv209oINjvdZgMcpa3Dyj7t4+x/Tzoz7lbXdzS9mM2Yazr ntIM1esRlBUlqAt8VUksakSPVUxYbe9+B2xvkE1/dkvYY0LmI6ZiK99NQAorXv7U NBsJR+F+J1HRo/m4n4gDdg== 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=fm1; t=1726490923; x= 1726577323; bh=lpEUdO/wPpSPwPKrfTr4hfW9fI0zZIvGI75OarIuJAs=; b=k 4k4d9yFw8sY6evTB+kV9OuV4jTq17VOM2kFZPj7An2LDwaKjUMAp7tyUofEQoOfc Z/vATI6dqSqbE6V7Z8NgD+fV3AXWDNGAtWcuFpx1OQRnNFfJ0dwkBXNj8GudyLPN ibnrOrmsRSijlg4D8by4aPU7v8fllPUZftK0SlkjYKDjMnQH1hb5bk0PtA0RI9KJ 9KG5gOoBRAT1VgOpNF22b63/66RhnUrX8cjZUKdE3uu/3X7NCTLjnYYkLZcx0pGy ikFOMjRtp2Lg2/gsHGPGpcOH4TBdGoBZC8CONa89uRz2GxaXgq1T77GuuAcYDVx9 9rqGsffzrkJBXAAWlUJKg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrudekhedgheeiucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdggtfgfnhhsuhgsshgtrhhisggvpdfu rfetoffkrfgpnffqhgenuceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnh htshculddquddttddmnecujfgurhephffvvefufffkjghfggfgtgesthhqredttddtjeen ucfhrhhomhepvfhhohhmrghsucfoohhnjhgrlhhonhcuoehthhhomhgrshesmhhonhhjrg hlohhnrdhnvghtqeenucggtffrrghtthgvrhhnpeehvddvueefuddvheeutdfgvdevffdu vdegjeeutdfhueevfeehffektedugfejleenucffohhmrghinhepphihthhhohhnrdhorh hgnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepthhh ohhmrghssehmohhnjhgrlhhonhdrnhgvthdpnhgspghrtghpthhtohepuddupdhmohguvg epshhmthhpohhuthdprhgtphhtthhopehjuhhrrghjrdhlihhnkhgvshesphgrnhhthhgv ohhnrdhtvggthhdprhgtphhtthhopehhohhnnhgrphhprgdrnhgrghgrrhgrhhgrlhhlih esrghrmhdrtghomhdprhgtphhtthhopehjshhpvgifohgtkhesihholhdruhhnhhdrvggu uhdprhgtphhtthhopehprhhosggssehiohhlrdhunhhhrdgvughupdhrtghpthhtohepph gruhhlrdhsiigtiigvphgrnhgvkhesrghrmhdrtghomhdprhgtphhtthhopehluhgtrgdr vhhiiiiirghrrhhosegrrhhmrdgtohhmpdhrtghpthhtohepnhhprhgrthhtvgesihholh druhhnhhdrvgguuhdprhgtphhtthhopegumhgrrhigsehiohhlrdhunhhhrdgvughupdhr tghpthhtoheprghlvgigrdgthhgrphhmrghnsegrrhhmrdgtohhm X-ME-Proxy: Feedback-ID: i47234305:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Mon, 16 Sep 2024 08:48:41 -0400 (EDT) From: Thomas Monjalon To: Juraj =?UTF-8?B?TGlua2XFoQ==?= Cc: Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu, dmarx@iol.unh.edu, alex.chapman@arm.com, dev@dpdk.org, Bruce Richardson Subject: Re: [PATCH v19 5/5] dts: add API doc generation Date: Mon, 16 Sep 2024 14:48:39 +0200 Message-ID: <10586268.nUPlyArG6x@thomas> In-Reply-To: <80f57b93-eb91-48b1-ada9-d23fd45f8a59@pantheon.tech> References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <13597798.dW097sEU6C@thomas> <80f57b93-eb91-48b1-ada9-d23fd45f8a59@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 16/09/2024 10:51, Juraj Linke=C5=A1: > On 12. 9. 2024 22:09, Thomas Monjalon wrote: > > 21/08/2024 17:02, Juraj Linke=C5=A1: > >> + req_deps =3D _get_dependencies(_DTS_DEP_FILE_PATH) > >> + req_deps.pop('python') > >> + > >> + for req_dep, dep_data in (req_deps | _EXTRA_DEPS).items(): > >=20 > > Please could you explain somewhere why _EXTRA_DEPS is needed? >=20 > I'll add this comment above the variable: > # The names of packages used in import statements may be different from=20 > distribution package names. > # We get distribution package names from pyproject.toml. > # _EXTRA_DEPS adds those import names which don't match their=20 > distribution package name. Good > > I feel the need for dependencies should be explained in the script. >=20 > From my point of view, the script gets the dependencies and it's up to=20 > the caller how they use the list of dependencies. >=20 > The caller is conf.py and there's a bit of an explanation: > # Get missing DTS dependencies. Add path to buildtools to find the=20 > get_missing_imports function. >=20 > And then: > # Ignore missing imports from DTS dependencies. >=20 > So basically get the dependencies so we know what to ignore. >=20 > But I could add something to the script if this is not enough. The unclear part is how it works without these dependencies. > >> +# initialize common Doxygen configuration > >> +cdata =3D configuration_data() > >> + > >> +subdir('dts') > >=20 > > Why inserting DTS first before generating DPDK API doc? >=20 > I wanted to put it before subdir_done(). Maybe we could put=20 > subdir('dts') in the else branch and also at the end of the meson.build=20 > file. That could be better. Yes > >> + # Intersphinx allows linking to external projects, such as Python= docs. > >> + intersphinx_mapping =3D {'python': ('https://docs.python.org/3', = None)} > >=20 > > I'm not sure about the need for this intersphinx. >=20 > It's not stricly needed, but it produces better documentation, with=20 > links to Python docs for classes and other things found there. >=20 > For example: > :class:`~argparse.Action` in a docstring will link to=20 > https://docs.python.org/3/library/argparse.html#argparse.Action If you think it helps, I'm fine.