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 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 ; 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: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeeggdejtdcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdejnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhephfduteeludekieeitdfggfeggeelvdevtdefleelkeelhfeugffg keetjeehfffhnecuffhomhgrihhnpegtohhnfhdrihhnpdhphihthhhonhdrohhrghenuc evlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehthhhomhgr shesmhhonhhjrghlohhnrdhnvghtpdhnsggprhgtphhtthhopedt X-ME-Proxy: Feedback-ID: i47234305:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 30 Jul 2024 09:51: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, Luca Vizzarro 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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