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 B785F456F4;
Tue, 30 Jul 2024 16:41:48 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 860D44067C;
Tue, 30 Jul 2024 16:41:33 +0200 (CEST)
Received: from fout1-smtp.messagingengine.com (fout1-smtp.messagingengine.com
[103.168.172.144])
by mails.dpdk.org (Postfix) with ESMTP id 7FA2B400D7
for <dev@dpdk.org>; Tue, 30 Jul 2024 15:51:40 +0200 (CEST)
Received: from compute2.internal (compute2.nyi.internal [10.202.2.46])
by mailfout.nyi.internal (Postfix) with ESMTP id E7C8213802AF;
Tue, 30 Jul 2024 09:51:39 -0400 (EDT)
Received: from mailfrontend2 ([10.202.2.163])
by compute2.internal (MEProxy); Tue, 30 Jul 2024 09:51: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=1722347499;
x=1722433899; bh=BbNvvwEQciiqVnmkHjJ8fIH9JzrgYsS+0NzpcIqhoNE=; b=
rdmDm/8s5TlBYEcG2gg7LckX/tt4CcmOkokFmUulxzfvs/pJHV4G9dWcSNHbmVzd
054gVPcGe4yPNzVA+xZsh7HIYWHjsbqDz8X8ziEWNhTxGWqJIi02/z0RYKJ0abR+
yDpdurkI7gn382jXHEJF5XbRI0lknX87c08kmaLcOsWWa3YX52I8xpSNs4dhowur
1ninsR7w0DBICQ8+4BFqj4EwKlZPEw1F80G3QV8zqykzGumU38Ta3Rc5SHr7PSZa
TbxQSoHB4MBZ3jt6ELOAL5AAaXlNZfkV+s+9s/C0l2rRt9T4m104aN4mDyiF6XC6
HO6ePZVrzZjsYXvQoZDvrQ==
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=1722347499; x=
1722433899; bh=BbNvvwEQciiqVnmkHjJ8fIH9JzrgYsS+0NzpcIqhoNE=; b=Z
EkpfpLc6xLpYPdognnXScMrjJex9A8ocj7wRJMwFWYUMH9BLcMi/50zjlZ5ohjCS
qPMeeddRUnCMHNH+E6ZpJOBCRcDJ0ZC17lX1QNvCUYBrsY3pQi9hTvImpfpmGwZi
bx4p8dbwwfn0XZNG/uKceSbe7U6a3B3O/5XM9s6o/CTZb+H9kzaicK4ej3hxRuvS
wp/b8zZzh2PlF4y84RrsVLZm3ZDl2i/bBEP35ypRpWEKsIWseNIbuHOOuuMv0fDY
/9iuMZwA8eyWDZyIC8LubSQAv2OJvGe4BiU9ueJEkSCA6sHQ8Xwi4LfzjFdL7Mq5
ITBWWiwRr5/Oe74zwjPQQ==
X-ME-Sender: <xms:6--oZmRCJung9psTsYUaHaWXR9FJRNrvG0Txftg9m83cmgtMgRKPXw>
<xme:6--oZrw4FtmWoagl2v2d6yf_p-3tLW3ffX0rbgK5U6BHdMtYXb819Nkyhdpp-y4UG
JZfk-P7Sdieg1KPeQ>
X-ME-Received: <xmr:6--oZj1oH7J_Axp7ZLwwL4cN1b3AKbEB5c1UTqHyUUUSwrItLe5kcWIcf_VBtHfqcpRohWwnYbJph09OMFmPXSrpzg>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeeggdejtdcutefuodetggdotefrodftvf
curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu
uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc
fjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdejnecuhfhrohhmpefvhhhomhgr
shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg
ftrfgrthhtvghrnhephfduteeludekieeitdfggfeggeelvdevtdefleelkeelhfeugffg
keetjeehfffhnecuffhomhgrihhnpegtohhnfhdrihhnpdhphihthhhonhdrohhrghenuc
evlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehthhhomhgr
shesmhhonhhjrghlohhnrdhnvghtpdhnsggprhgtphhtthhopedt
X-ME-Proxy: <xmx:6--oZiCcJVLH2JWc8KjtzI51xCYGgXidJ6mJ99ilYzetJWcKQmyslg>
<xmx:6--oZvj9C64hHDuSNHW5tKiAF-yxj5aNrVobd46T16rVcnbWjfeicg>
<xmx:6--oZuqOzpI9WnEbvxdMkM8INO7k_HW1i-8Rq8q1be-JJmWX57NVkQ>
<xmx:6--oZiinrjTPD278c9vUv0Hb7Sz8csNkLKE1HWuX_AgzQzVpf5fayw>
<xmx:6--oZkb-ze0w72ppww3TTjZN217o5fbAHNw0HEdAbpYj3MEwNisclTbZ>
Feedback-ID: i47234305:Fastmail
Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue,
30 Jul 2024 09:51: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,
Luca Vizzarro <luca.vizzarro@arm.com>
Subject: Re: [PATCH v8 5/5] dts: add API doc generation
Date: Tue, 30 Jul 2024 15:51:33 +0200
Message-ID: <10378083.0AQdONaE2F@thomas>
In-Reply-To: <20240712085724.21065-6-juraj.linkes@pantheon.tech>
References: <20231115133606.42081-1-juraj.linkes@pantheon.tech>
<20240712085724.21065-1-juraj.linkes@pantheon.tech>
<20240712085724.21065-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
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.
What is changed in the sidebar?
> --- a/doc/api/doxy-api-index.md
> +++ b/doc/api/doxy-api-index.md
> @@ -244,3 +244,6 @@ The public API headers are grouped by topics:
> [experimental APIs](@ref rte_compat.h),
> [ABI versioning](@ref rte_function_versioning.h),
> [version](@ref rte_version.h)
> +
> +- **tests**:
> + [**DTS**](@dts_api_main_page)
OK looks good
> --- a/doc/api/doxy-api.conf.in
> +++ b/doc/api/doxy-api.conf.in
> @@ -124,6 +124,8 @@ SEARCHENGINE =3D YES
> SORT_MEMBER_DOCS =3D NO
> SOURCE_BROWSER =3D YES
> =20
> +ALIASES =3D "dts_api_main_page=3D@DTS_API_MAIN_PAGE@"
Why is it needed?
That's the only way to reference it in doxy-api-index.md?
Would be nice to explain in the commit log.
> --- a/doc/api/meson.build
> +++ b/doc/api/meson.build
> +# 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)
This comment is really obscure.
> +cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.ht=
ml'))
Oh I think I get it:
- DTS_API_MAIN_PAGE is the Meson variable
- dts_api_main_page is the Doxygen variable
> +# Napoleon enables the Google format of Python doscstrings, used in DTS
> +# Intersphinx allows linking to external projects, such as Python docs, =
also used in DTS
Close sentences with a dot, it is easier to read.
> +extensions =3D ['sphinx.ext.napoleon', 'sphinx.ext.intersphinx']
> +
> +# DTS Python docstring options
> +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'
> +napoleon_numpy_docstring =3D False
> +napoleon_attr_annotations =3D True
> +napoleon_preprocess_types =3D True
> +add_module_names =3D False
> +toc_object_entries =3D True
> +toc_object_entries_show_parents =3D 'hide'
> +intersphinx_mapping =3D {'python': ('https://docs.python.org/3', None)}
> +
> +dts_root =3D environ.get('DTS_ROOT')
Why does it need to be passed as an environment variable?
Isn't it a fixed absolute path?
> +if dts_root:
> + path.append(dts_root)
> + # DTS Sidebar config
> + html_theme_options =3D {
> + 'collapse_navigation': False,
> + 'navigation_depth': -1,
> + }
[...]
> +To build DTS API docs, install the dependencies with Poetry, then enter =
its shell:
I don't plan to use Poetry on my machine.
Can we simply describe the dependencies even if the versions are not specif=
ied?
> +
> +.. 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
Don't we rely on the Meson option "enable_docs"?
> +
> +The output is generated in ``build/doc/api/dts/html``.
> +
> +.. Note::
In general the RST expressions are lowercase.
> +
> + Make sure to fix any Sphinx warnings when adding or updating docstrin=
gs,
> + and also run the ``devtools/dts-check-format.sh`` script and address =
any issues it finds.
It looks like something to write in the contributing guide.
> +++ b/dts/doc/meson.build
> @@ -0,0 +1,27 @@
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2023 PANTHEON.tech s.r.o.
> +
> +sphinx =3D find_program('sphinx-build', required: false)
> +sphinx_apidoc =3D find_program('sphinx-apidoc', required: false)
> +
> +if not sphinx.found() or not sphinx_apidoc.found()
You should include the option "enable_docs" here.
> + subdir_done()
> +endif