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 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 <dev@dpdk.org>; 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: <xms:hUrjZtdD7BkCvxssW8iwiqGxI_wcaTUQSWIWFnLG40DMOuO_iFIzPA>
 <xme:hUrjZrMotpICMRjumd-vouAmWLKQRSQLNcYqaOUAY2nKAuDu15SgxZ9F_e3Cfw08t
 DBWuyL83gNJVo2Axw>
X-ME-Received: <xmr:hUrjZmh-hNYmscfoU77No2vFUSp-iF_CPPvXCpnmbembUeBMpn82A_9iCE6UX-W4MZyhxurOnY2RRIFw8I8GYURJjg>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrudejfedgudegjecutefuodetggdotefrod
 ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpggftfghnshhusghstghrihgsvgdp
 uffrtefokffrpgfnqfghnecuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivg
 hnthhsucdlqddutddtmdenucfjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdej
 necuhfhrohhmpefvhhhomhgrshcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjh
 grlhhonhdrnhgvtheqnecuggftrfgrthhtvghrnhephedvvdeufeduvdehuedtgfdvveff
 uddvgeejuedthfeuveefheffkeetudfgjeelnecuffhomhgrihhnpehphihthhhonhdroh
 hrghenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpeht
 hhhomhgrshesmhhonhhjrghlohhnrdhnvghtpdhnsggprhgtphhtthhopeduvddpmhhoug
 gvpehsmhhtphhouhhtpdhrtghpthhtohepjhhurhgrjhdrlhhinhhkvghssehprghnthhh
 vghonhdrthgvtghhpdhrtghpthhtohephhhonhhnrghpphgrrdhnrghgrghrrghhrghllh
 hisegrrhhmrdgtohhmpdhrtghpthhtohepjhhsphgvfihotghksehiohhlrdhunhhhrdgv
 ughupdhrtghpthhtohepphhrohgssgesihholhdruhhnhhdrvgguuhdprhgtphhtthhope
 hprghulhdrshiitgiivghprghnvghksegrrhhmrdgtohhmpdhrtghpthhtoheplhhutggr
 rdhvihiiiigrrhhrohesrghrmhdrtghomhdprhgtphhtthhopehnphhrrghtthgvsehioh
 hlrdhunhhhrdgvughupdhrtghpthhtohepughmrghrgiesihholhdruhhnhhdrvgguuhdp
 rhgtphhtthhopegrlhgvgidrtghhrghpmhgrnhesrghrmhdrtghomh
X-ME-Proxy: <xmx:hUrjZm-uvlxTewZH_YcHrnEhKUr9OltYreAseUwxzfgiSqoLYtFsjg>
 <xmx:hUrjZpvDfxqRK2t2152F7RBdxniSlxSsjPRkv5b5oAOR8heCSuA9dw>
 <xmx:hUrjZlEn7k9h8RU4jPCJLepPRPAKylkpOZuk3XUfpB4tBAq4wiUvwQ>
 <xmx:hUrjZgMVA-9t5AFwhfETL_wbVrXpPFQPZlKRKXXM-goJFflDtzvtzw>
 <xmx:hkrjZiFc-gGzNbL8KnILJIIhWnS4v4JNg5YbE6UOdAEGmAgeotyie3IY>
Feedback-ID: i47234305:Fastmail
Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu,
 12 Sep 2024 16:09:40 -0400 (EDT)
From: Thomas Monjalon <thomas@monjalon.net>
To: Juraj =?UTF-8?B?TGlua2XFoQ==?= <juraj.linkes@pantheon.tech>
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==?= <juraj.linkes@pantheon.tech>,
 Bruce Richardson <bruce.richardson@intel.com>
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 <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

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 <bluca@debian.org>
> =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 <thomas@monjalon.net>