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 6CC7945972; Thu, 12 Sep 2024 22:09:44 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 37ADC4029B; Thu, 12 Sep 2024 22:09:44 +0200 (CEST) Received: from fhigh3-smtp.messagingengine.com (fhigh3-smtp.messagingengine.com [103.168.172.154]) by mails.dpdk.org (Postfix) with ESMTP id 2FD624028F for ; Thu, 12 Sep 2024 22:09:43 +0200 (CEST) Received: from phl-compute-03.internal (phl-compute-03.phl.internal [10.202.2.43]) by mailfhigh.phl.internal (Postfix) with ESMTP id A2816114017D; Thu, 12 Sep 2024 16:09:42 -0400 (EDT) Received: from phl-mailfrontend-02 ([10.202.2.163]) by phl-compute-03.internal (MEProxy); Thu, 12 Sep 2024 16:09:42 -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=1726171782; x=1726258182; bh=aEYHpX5cXdaoLtWpK0pgIxR1C7+NV2S6jtZQlxHNyq4=; b= Hr15qur/3mUldI34XO9jdoqhoEY17mTAncuyOYclXjTsgmkk32qH3beSUxp9Xpfs JNfYfeG3xIfS5RLjirx3tMAomlu7piMwlbdnqsYaPIUIGSNgSGOXCae7exZD6pU0 dysV+d3zSlHzdmHjRhmzunCklr13ihV68qopfm+MET0rp1XOP6TSOh/JLj02cwHg ANtOM0KCdMLRezsTl/CTFZ7Few/mL9/EpjndKMpol45pw4QVN/b/VAks76qT2Zs8 ScLTTpL2AVeSLArJHu2cA98sCpHLF4FzMRkbfspt2CpVu1zoSf+ar51/ywvFAWG+ zI5VcYenrxMi9KIWbg61ow== 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=1726171782; x= 1726258182; bh=aEYHpX5cXdaoLtWpK0pgIxR1C7+NV2S6jtZQlxHNyq4=; b=N KPMdl8LuKilK4Gz+Sj0937uuOtBrjpFzs9Avw8CCpWyTumXhWGpiplQ5F1oJFn6y nyp7Al/j/VpEEtrKBdoc2TkP4JAluegvq4QMnKELIdm5QMwZ1uzu0c31Q/IGq9lj MpcCakPUZohYWavLAxPimrqbHBfFi19fpfJ4hY2TaZY0C2VM6WeVTNTJAxJ6hsnW W4JVDB30fs2Zc8DvzG2DCHH2Oo6mdGnFjmn6uOFPw9oSicw0FCRBFbuUdXkpAFM2 0MMgGLOnq69D4QD0CqozoZHhLqazHX2v9x0Z44KuIgpKJ3cOQaT7Fm20ZnnR4rQa MG/OuKPOXRtWg2E62etbw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrudejfedgudegjecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpggftfghnshhusghstghrihgsvgdp uffrtefokffrpgfnqfghnecuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivg hnthhsucdlqddutddtmdenucfjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdej necuhfhrohhmpefvhhhomhgrshcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjh grlhhonhdrnhgvtheqnecuggftrfgrthhtvghrnhephedvvdeufeduvdehuedtgfdvveff uddvgeejuedthfeuveefheffkeetudfgjeelnecuffhomhgrihhnpehphihthhhonhdroh hrghenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpeht hhhomhgrshesmhhonhhjrghlohhnrdhnvghtpdhnsggprhgtphhtthhopeduvddpmhhoug gvpehsmhhtphhouhhtpdhrtghpthhtohepjhhurhgrjhdrlhhinhhkvghssehprghnthhh vghonhdrthgvtghhpdhrtghpthhtohephhhonhhnrghpphgrrdhnrghgrghrrghhrghllh hisegrrhhmrdgtohhmpdhrtghpthhtohepjhhsphgvfihotghksehiohhlrdhunhhhrdgv ughupdhrtghpthhtohepphhrohgssgesihholhdruhhnhhdrvgguuhdprhgtphhtthhope hprghulhdrshiitgiivghprghnvghksegrrhhmrdgtohhmpdhrtghpthhtoheplhhutggr rdhvihiiiigrrhhrohesrghrmhdrtghomhdprhgtphhtthhopehnphhrrghtthgvsehioh hlrdhunhhhrdgvughupdhrtghpthhtohepughmrghrgiesihholhdruhhnhhdrvgguuhdp rhgtphhtthhopegrlhgvgidrtghhrghpmhgrnhesrghrmhdrtghomh X-ME-Proxy: Feedback-ID: i47234305:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu, 12 Sep 2024 16:09:40 -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, Juraj =?UTF-8?B?TGlua2XFoQ==?= , Bruce Richardson Subject: Re: [PATCH v19 5/5] dts: add API doc generation Date: Thu, 12 Sep 2024 22:09:38 +0200 Message-ID: <13597798.dW097sEU6C@thomas> In-Reply-To: <20240821150254.158912-6-juraj.linkes@pantheon.tech> References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240821150254.158912-1-juraj.linkes@pantheon.tech> <20240821150254.158912-6-juraj.linkes@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 21/08/2024 17:02, Juraj Linke=C5=A1: > +if 'dts' in src: > + os.environ['DTS_BUILD'] =3D "y" That's more precisely "DTS doc build". I think the variable name DTS_BUILD may be confusing. [...] > --- /dev/null > +++ b/buildtools/get-dts-runtime-deps.py > @@ -0,0 +1,95 @@ > +#!/usr/bin/env python3 > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(c) 2024 PANTHEON.tech s.r.o. > +# extra blank line above can be removed > + > +"""Utilities for DTS dependencies. > + > +The module can be used as an executable script, > +which verifies that the running Python version meets the version require= ment of DTS. > +The script exits with the standard exit codes in this mode (0 is success= , 1 is failure). Given it is just doing a check by default, the script name could be "check-dts-requirements". > + > +The module also contains a function, get_missing_imports, > +which looks for runtime dependencies in the DTS pyproject.toml file > +and returns a list of module names used in an import statement (import p= ackages) that are missing. > +This function is not used when the module is run as a script and is avai= lable to be imported. > +""" [...] > + req_deps =3D _get_dependencies(_DTS_DEP_FILE_PATH) > + req_deps.pop('python') > + > + for req_dep, dep_data in (req_deps | _EXTRA_DEPS).items(): Please could you explain somewhere why _EXTRA_DEPS is needed? [...] > +++ b/doc/api/dts/meson.build > @@ -0,0 +1,31 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(c) 2023 PANTHEON.tech s.r.o. > + > +sphinx =3D find_program('sphinx-build', required: get_option('enable_doc= s')) > +if not sphinx.found() > + subdir_done() > +endif > + > +python_ver_satisfied =3D run_command(get_dts_runtime_deps, check: false)= =2Ereturncode() > +if python_ver_satisfied !=3D 0 > + subdir_done() > +endif Looks simple. So if I have the right Python but some dependencies are missing, it will still work the same, right? I feel the need for dependencies should be explained in the script. [...] > --- a/doc/api/meson.build > +++ b/doc/api/meson.build > @@ -1,6 +1,11 @@ > # SPDX-License-Identifier: BSD-3-Clause > # Copyright(c) 2018 Luca Boccassi > =20 > +# initialize common Doxygen configuration > +cdata =3D configuration_data() > + > +subdir('dts') Why inserting DTS first before generating DPDK API doc? [...] > # set up common Doxygen configuration > -cdata =3D configuration_data() > cdata.set('VERSION', meson.project_version()) > cdata.set('API_EXAMPLES', join_paths(dpdk_build_root, 'doc', 'api', 'exa= mples.dox')) > cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api')) > diff --git a/doc/guides/conf.py b/doc/guides/conf.py > index 0f7ff5282d..d7f3030838 100644 > --- a/doc/guides/conf.py > +++ b/doc/guides/conf.py > @@ -10,7 +10,7 @@ > from os.path import basename > from os.path import dirname > from os.path import join as path_join > -from sys import argv, stderr > +from sys import argv, stderr, path > =20 > import configparser > =20 > @@ -58,6 +58,48 @@ > ("tools/devbind", "dpdk-devbind", > "check device status and bind/unbind them from drivers", "= ", 8)] > =20 > +# DTS API docs additional configuration > +if environ.get('DTS_BUILD'): > + extensions =3D ['sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx= =2Eext.intersphinx'] > + # Napoleon enables the Google format of Python doscstrings. > + napoleon_numpy_docstring =3D False > + napoleon_attr_annotations =3D True > + napoleon_preprocess_types =3D True > + > + # Autodoc pulls documentation from code. > + autodoc_default_options =3D { > + 'members': True, > + 'member-order': 'bysource', > + 'show-inheritance': True, > + } > + autodoc_class_signature =3D 'separated' > + autodoc_typehints =3D 'both' > + autodoc_typehints_format =3D 'short' > + autodoc_typehints_description_target =3D 'documented' > + > + # Intersphinx allows linking to external projects, such as Python do= cs. > + intersphinx_mapping =3D {'python': ('https://docs.python.org/3', Non= e)} I'm not sure about the need for this intersphinx. > + > + # DTS docstring options. > + add_module_names =3D False > + toc_object_entries =3D True > + toc_object_entries_show_parents =3D 'hide' > + # DTS Sidebar config. > + html_theme_options =3D { > + 'collapse_navigation': False, > + 'navigation_depth': -1, # unlimited depth > + } > + > + # Add path to DTS sources so that Sphinx can find them. > + dpdk_root =3D dirname(dirname(dirname(__file__))) > + path.append(path_join(dpdk_root, 'dts')) > + > + # Get missing DTS dependencies. Add path to buildtools to find the g= et_missing_imports function. > + path.append(path_join(dpdk_root, 'buildtools')) > + import importlib > + # Ignore missing imports from DTS dependencies. > + autodoc_mock_imports =3D importlib.import_module('get-dts-runtime-de= ps').get_missing_imports() [...] > +the corresponding changes must be made to DTS api doc sources in ``doc/a= pi/dts``. api -> API Except minor corrections and explanations, it looks good. You can add my ack to the final version. Acked-by: Thomas Monjalon