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 A077E45835; Wed, 21 Aug 2024 17:24:25 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 3A517402E8; Wed, 21 Aug 2024 17:24:25 +0200 (CEST) Received: from mail-pl1-f175.google.com (mail-pl1-f175.google.com [209.85.214.175]) by mails.dpdk.org (Postfix) with ESMTP id 46A05402B5 for ; Wed, 21 Aug 2024 17:24:23 +0200 (CEST) Received: by mail-pl1-f175.google.com with SMTP id d9443c01a7336-202146e93f6so54051585ad.3 for ; Wed, 21 Aug 2024 08:24:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1724253862; x=1724858662; 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=3pi7N/Wr2/s69BAVWVQgUV0088Zg/gb1EttXNAsRkfY=; b=fGoJTaqhqCseJLVw7lUdduEDFX+HQtiiZUphHSLiwQ2FiVdurUvnLoMxdiQs8fCFMe xYauCC1QwR6UkjAxpt/rQJBCrWMrIXWwW6+M77YBfUDo4I14xyxhtjKtMFBdu33Ncj9D p6kULi/O43UUy88eDT1DkVHg+rwO9ld69t5Os= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1724253862; x=1724858662; 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=3pi7N/Wr2/s69BAVWVQgUV0088Zg/gb1EttXNAsRkfY=; b=I6727AcliAnxGqBvqU4j2+Mk9jRXef1v2qGLsgRj7b2FGeDOSTyFotE8QtrZ5ePKWW +/iPIMQLTrToPF64QOp1RiFISMryOPnoqqLLAvUmmmVocTbC5H8K2ooZ48Rdr4atuMv8 JsdX9oSu31YFx5n1J1jzQ6fAFdfslJ455FoNseT9kFMnaKSCnmuJyIZJbLiJsILSIOfU dBjJm/o+R9HarvyMJz9k/FoOq9t0eo/pUodxxH5ibKOOPE5dWvDiIWLKMogTSsVBtauS 7cTug4rhPo2i5Pcb+sD3SwJzNLwwXI+2D1UoT0ApgsrvaX3anh75ePm96XNAT647jBpd wcwA== X-Forwarded-Encrypted: i=1; AJvYcCXZNAR437FlV9ELt1wb80RURcVXKjdFf3Ehvmc61SPgnPCw8MesBNTGE4ZW7k1tmxGWw7Q=@dpdk.org X-Gm-Message-State: AOJu0YxNkdONwb1Q3jw/eWssHRPtw+4T0XqFL4lpJ4Sd2B9LpgkXtHvt ywV060S7Rd9et98Ij+7R4WZ5M6cUuN/9aRhQuTD5JaQk8VHWZK7rV5F4pScFLpu2V2YmDEuIbva ftD19tYmJgpUXfHNBaJvTyvPp4qm3dHTz5YGhzQ== X-Google-Smtp-Source: AGHT+IHZ6yngJRm1LIR1kO57VyxsM7ImZ9gNIZE9jYKFubJeHOvghhNKbFcY9NsQTgCPB4YukcfGGbXGGhpHhAe1uQA= X-Received: by 2002:a17:902:e842:b0:202:244e:a0b3 with SMTP id d9443c01a7336-203681d1997mr29843185ad.46.1724253862199; Wed, 21 Aug 2024 08:24:22 -0700 (PDT) MIME-Version: 1.0 References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240821150254.158912-1-juraj.linkes@pantheon.tech> <20240821150254.158912-6-juraj.linkes@pantheon.tech> In-Reply-To: <20240821150254.158912-6-juraj.linkes@pantheon.tech> From: Dean Marx Date: Wed, 21 Aug 2024 11:24:34 -0400 Message-ID: Subject: Re: [PATCH v19 5/5] dts: add API doc generation To: =?UTF-8?Q?Juraj_Linke=C5=A1?= Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu, alex.chapman@arm.com, dev@dpdk.org, Bruce Richardson Content-Type: multipart/alternative; boundary="000000000000f59e0d0620332277" 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 --000000000000f59e0d0620332277 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Wed, Aug 21, 2024 at 11:03=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. > Tested-by: Dean Marx --000000000000f59e0d0620332277 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Wed, Aug 21, 2024 at 11:03=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.

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