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 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 <dev@dpdk.org>; Wed, 21 Aug 2024 17:24:23 +0200 (CEST) Received: by mail-pl1-f175.google.com with SMTP id d9443c01a7336-202146e93f6so54051585ad.3 for <dev@dpdk.org>; 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 <dmarx@iol.unh.edu> Date: Wed, 21 Aug 2024 11:24:34 -0400 Message-ID: <CABD7UXOQ=c31iuOgkRREPpibwZtPU=MQQ9xK_HYqN1ACQBKczg@mail.gmail.com> Subject: Re: [PATCH v19 5/5] dts: add API doc generation To: =?UTF-8?Q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech> 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 <bruce.richardson@intel.com> 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 <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 --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 <juraj.linkes@pa= ntheon.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 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 <dmarx@iol.unh.edu> --000000000000f59e0d0620332277 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div dir=3D"ltr">On Wed, Aug 21, 2024 at 11:03=E2=80=AFAM = Juraj Linke=C5=A1 <juraj.linkes@pantheon.tech> wrote:<br></div><div c= lass=3D"gmail_quote"><blockquote class=3D"gmail_quote" style=3D"margin:0px = 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">The = tool used to generate DTS API docs is Sphinx, which is already in<br> use in DPDK. The same configuration is used to preserve style with one<br> DTS-specific configuration (so that the DPDK docs are unchanged) that<br> modifies how the sidebar displays the content. There's other Sphinx<br> configuration related to Python docstrings which doesn't affect DPDK do= c<br> build. All new configuration is in a conditional block, applied only<br> when DTS API docs are built to not interfere with DPDK doc build.<br> <br> Sphinx generates the documentation from Python docstrings. The docstring<br= > format is the Google format [0] which requires the sphinx.ext.napoleon<br> extension. The other extension, sphinx.ext.intersphinx, enables linking<br> to objects in external documentations, such as the Python documentation.<br= > <br> There is one requirement for building DTS docs - the same Python version<br= > as DTS or higher, because Sphinx's autodoc extension imports the code.<= br> <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<br> packages are taken from the DTS pyproject.toml file.<br> <br> And finally, the DTS API docs can be accessed from the DPDK API doxygen<br> page.<br></blockquote><div><br></div><div>Tested-by: Dean Marx <<a href= =3D"mailto:dmarx@iol.unh.edu">dmarx@iol.unh.edu</a>>=C2=A0</div></div></= div> --000000000000f59e0d0620332277--