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 9E81F457C6; Wed, 14 Aug 2024 20:50:31 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D21674278F; Wed, 14 Aug 2024 20:50:30 +0200 (CEST) Received: from mail-pj1-f52.google.com (mail-pj1-f52.google.com [209.85.216.52]) by mails.dpdk.org (Postfix) with ESMTP id 799A840BA0 for ; Wed, 14 Aug 2024 20:50:28 +0200 (CEST) Received: by mail-pj1-f52.google.com with SMTP id 98e67ed59e1d1-2d3bdab22b1so79934a91.0 for ; Wed, 14 Aug 2024 11:50:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1723661427; x=1724266227; darn=dpdk.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=ERYsvJd6/vo1OBCpS02YqgrTIT0lBrkGbHUidOn45QY=; b=jtqP2xd6WInFBSmtw7htPmTZB6tDqw/QAhB1zIKRi8ISKQt7trwMxnjr++CceUPisZ 0+iqcghIJvcujSa0Q3TA83xLDYO6xX4kmbZfTjgw0JG76sX3Xh6gyw/tFdszUd1ICZMg yuH2WzyQWlaX21+jRMdyA1WODrklHhVd1P1UY= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723661427; x=1724266227; h=content-transfer-encoding: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=ERYsvJd6/vo1OBCpS02YqgrTIT0lBrkGbHUidOn45QY=; b=lDzCMzoTMNL1CEfemLL1dg2gxApVB0f+5bMhRVLR4EMAS/f2AJR7yiIxVMrHPiikdB C0nJI89wSVoMPt+bOIlwfeOKiXEHY87LseuJZz8GpMu1xObm3K6R7KWAekNPeWYsuWec Zde+qor+cOynDLLyRGN+dclT30pXOZm4bdkspsn/GrUmjHNrjRrBPUCDhVuLRFpL+Dz2 nOHnlqt4WXZkAme5bkXDi/PJMLgBRdjU4R3J6LXVR08ff8qUxi8hGuBZA9+tFxMeiw8w BjHObxPk9mGsDG/jtv7aNrOozYcLfEfJb//KDdHmUu7sReDSlbAL/ZVxMS7u2I6+/Gt4 pmqQ== X-Forwarded-Encrypted: i=1; AJvYcCWEhh7Bx/4f/ElOeq+TeVdgYQAuT3zCLnHRR/GAAur/lDenbAXDxeXnxnzavrL0bso9K4ggLjkTgxVglcI= X-Gm-Message-State: AOJu0YxsHYq1FUs+gaB0V3YF8+vGGyBbFntvPjLddR5Yk44SEGXT8i/g tckWL2PABpuz3z6Orm4FVTy7FdVzWfe2wtvKG6TWuBf8lA4VzQhGZByLmAFVy7mAX15DAWYeCFJ pdWDVfBuvF/1g9LEGTVUsiprsRTyDZSST6Nfu1A== X-Google-Smtp-Source: AGHT+IE6bTFfhTWbvRPWCs/fESwCXxgSmSHYbQXmwEsHUxUp2xRjjwi2vep+0XWw7MYY/47g0+luGDsNPSdy+/OzNq4= X-Received: by 2002:a17:90a:9a90:b0:2ca:4fca:2892 with SMTP id 98e67ed59e1d1-2d3aaa7af5cmr4224333a91.7.1723661427496; Wed, 14 Aug 2024 11:50:27 -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: Jeremy Spewock Date: Wed, 14 Aug 2024 14:50:16 -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, probb@iol.unh.edu, paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu, dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 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-docs= trings > > Signed-off-by: Juraj Linke=C5=A1 Reviewed-by: Jeremy Spewock