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 2AE6445818; Mon, 19 Aug 2024 19:49:49 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E60A84026C; Mon, 19 Aug 2024 19:49:48 +0200 (CEST) Received: from mail-pf1-f179.google.com (mail-pf1-f179.google.com [209.85.210.179]) by mails.dpdk.org (Postfix) with ESMTP id 3AA92400D6 for ; Mon, 19 Aug 2024 19:49:47 +0200 (CEST) Received: by mail-pf1-f179.google.com with SMTP id d2e1a72fcca58-70d199fb3dfso3784590b3a.3 for ; Mon, 19 Aug 2024 10:49:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1724089786; x=1724694586; darn=dpdk.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=dMax0xiNQ6Y7iNbYamMTXMH7EpC8dMTZuFbomNlSxBk=; b=Ga+pwcaxr0cCTQC+15TqPVIds0RYpSutQ764VgxCFzeL6N/0k4r/I59uR8uwDjYs9G MKSElF/SGTcY9CWfgnkM7lOylSz6XGVHNL26eDjAi1mF3srRUOEYUKNUPMU0LcwfeeD8 +y8RU7MYz3Ip0B3hH/BsWfi9rjl//1Hj4aA3s= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1724089786; x=1724694586; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=dMax0xiNQ6Y7iNbYamMTXMH7EpC8dMTZuFbomNlSxBk=; b=J6EfrBit2s9E90VTX4tvml8632Xsrvv7uO3yseZiDIE0OC/MEQGcpmhf+pRu9socSi D9aHwMNoHTBhCSPGdx/DtqhY4ZIRN8jIhO8bSbJ/z4bAkuv3uyAFXUmuOoOdoBp+TWVj q8C+Ww5YPxCi2eJFNyfCIw5hVhr/4ljLo5zDSCB/HiY8lX0mg6TxhPhYmFFB+1ppmi8q Wm+hB38xop9bCLDP1F/ZsIoFMSGZWZDkbGercS4xLgbLmBnu0S1L0edzs1q5dbJOWLR8 UtSPdheFaHS599tA8dURApFaskXrKhLAvMzHLfS9mgP3PHvBLLYJ7KXJyqQ1LrG4zzHY 9++Q== X-Forwarded-Encrypted: i=1; AJvYcCU9lBvtwEiC+6H/Tin/mQu+hSQYu2dKLiAYIcqYbXAtGMXmG+w3IL7RTa9bnVDOyrbOpTtfCv91bKuYjL0= X-Gm-Message-State: AOJu0YwOelyuEvxiyqX3EN+BHuDmgn6Mfhu3nDQeTIocm9nzaNuvkGGY NWb0Nqwm4no8EAr/6UQmy0nlND0hw8B5A4y4ial9zJ/u5oKaLtxFBTAYXgRZ3E8NNvWehyhtE4F R3Xx+kB6MbwRce9//lgoZVIJrmcrWikE/mNWk/A== X-Google-Smtp-Source: AGHT+IGKPLk+/TTbVqrAUT3ZJiXTuOgjZlS5K0CWoZsUpnl/JEnukXzP3mz3RFyYWk4pXcqGMs4xsKD+D8/VfGLrT18= X-Received: by 2002:a05:6a21:2d86:b0:1c6:ae03:6882 with SMTP id adf61e73a8af0-1c904f67c7amr14983451637.9.1724089786135; Mon, 19 Aug 2024 10:49:46 -0700 (PDT) MIME-Version: 1.0 References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240814150535.239547-1-juraj.linkes@pantheon.tech> <20240814150535.239547-6-juraj.linkes@pantheon.tech> In-Reply-To: <20240814150535.239547-6-juraj.linkes@pantheon.tech> From: Dean Marx Date: Mon, 19 Aug 2024 13:49:58 -0400 Message-ID: Subject: Re: [PATCH v17 5/5] dts: add API doc generation To: =?UTF-8?Q?Juraj_Linke=C5=A1?= Cc: thomas@monjalon.net, 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 Content-Type: multipart/alternative; boundary="0000000000004391bf06200cefef" 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 --0000000000004391bf06200cefef Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Wed, Aug 14, 2024 at 11:05=E2=80=AFAM Juraj Linke=C5=A1 wrote: > 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. There's other Sphinx > configuration related to Python docstrings which doesn't affect DPDK doc > build. All new configuration is in a conditional block, applied only > when DTS API docs are built to not interfere with DPDK doc build. > > Sphinx generates the documentation from Python docstrings. The docstring > format is the Google format [0] which requires the sphinx.ext.napoleon > extension. The other extension, sphinx.ext.intersphinx, enables linking > to objects in external documentations, such as the Python documentation. > > There is one requirement for building DTS docs - the same Python version > as DTS or higher, because Sphinx's autodoc extension imports the code. > > The dependencies needed to import the code don't have to be satisfied, > as the autodoc extension allows us to mock the imports. The missing > packages are taken from the DTS pyproject.toml file. > > And finally, the DTS API docs can be accessed from the DPDK API doxygen > page. > > [0] > https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrin= gs > > Signed-off-by: Juraj Linke=C5=A1 > Tested-by: Dean Marx --0000000000004391bf06200cefef Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


=
On Wed, Aug 14, 2024 at 11:05=E2=80= =AFAM Juraj Linke=C5=A1 <juraj.linkes@pantheon.tech> wrote:
=
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. There's other Sphinx
configuration related to Python docstrings which doesn't affect DPDK do= c
build. All new configuration is in a conditional block, applied only
when DTS API docs are built to not interfere with DPDK doc build.

Sphinx generates the documentation from Python docstrings. The docstring format is the Google format [0] which requires the sphinx.ext.napoleon
extension. The other extension, sphinx.ext.intersphinx, enables linking
to objects in external documentations, such as the Python documentation.
There is one requirement for building DTS docs - the same Python version as DTS or higher, because Sphinx's autodoc extension imports the code.<= br>
The dependencies needed to import the code don't have to be satisfied,<= br> as the autodoc extension allows us to mock the imports. The missing
packages are taken from the DTS pyproject.toml file.

And finally, the DTS API docs can be accessed from the DPDK API doxygen
page.

[0] https://google.github= .io/styleguide/pyguide.html#38-comments-and-docstrings

Signed-off-by: Juraj Linke=C5=A1 <juraj.linkes@pantheon.tech>

Tested-by: Dean Marx <dmarx@iol.unh.edu>=C2=A0
--0000000000004391bf06200cefef--