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 F25644577C; Fri, 9 Aug 2024 21:04:28 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D932042FB2; Fri, 9 Aug 2024 21:04:28 +0200 (CEST) Received: from mail-pf1-f175.google.com (mail-pf1-f175.google.com [209.85.210.175]) by mails.dpdk.org (Postfix) with ESMTP id DAD8942FA7 for ; Fri, 9 Aug 2024 21:04:26 +0200 (CEST) Received: by mail-pf1-f175.google.com with SMTP id d2e1a72fcca58-70eaf5874ddso1999217b3a.3 for ; Fri, 09 Aug 2024 12:04:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1723230266; x=1723835066; 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=TNF0czjU3mbvPQ1nRSIAmz2iZqiLSrfdNOZq5OW+lp8=; b=WlAGQZyQfu0cutbusLc4toCBp8OnvSxAcOxllMZIUuODh2HbmMTpLfKGOsMBz1MDRo 3/miqodMfXYWzt6yVt9UTMWnNpg3W3niPMyCXj8I4cuRFOCEUbqlf2jxop6OIYm6HnM1 WvnOwPvC2KEEmIMHOfuPlhu52zwO4pj0dOVpo= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723230266; x=1723835066; 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=TNF0czjU3mbvPQ1nRSIAmz2iZqiLSrfdNOZq5OW+lp8=; b=Vt6ASv76yZ7ktpQo9leYWk0kz946Lb6x1opUUspdvIRT63h7zun3skgOzNZKmGVf+m R6zGzwBQgg3ovZXrwuiDar9bhqqZnc5GhPmeeZN8s/o776D2MFGX1zllVf94KdMOVSDi FJZxqTwYyFP5c7QV4rODUyMUTn1URr3HPcqQDIrRcMxD2Ojukv0pnumN6Oe+qa7yy2X1 qAKg+8XXbpSe+aUEgkyedBXZJOHW5MxrNZu5kmbXA5sU90VCr0iGU3hG1TvGAtODPXOp DzB4ADnqLwHXIhmW4DsY6r7WCY7eGPuC3DgwlBb3qpO1mnPY2gnuEMC8FXy/D9vJJ2aC vH6w== X-Forwarded-Encrypted: i=1; AJvYcCWuGr6d06lAYKT6nIrKN/2hRkJ6717PzhD60kzt6t7HCkll4LT0bxxVgd4uRmHqW4YC4iFyGNFtLbHJpJA= X-Gm-Message-State: AOJu0Yx5mb1dtEpuM2kzLgWn3kTdakbCEwuw3WRBWkLVCq1oRF9BMwHf uAj87xLh4+2VJBeUg+xMEXAQJf60BdQw7T/fuNCwuNsInSov/oqVceq7MhVjq2VOH1UwaC23Wau 7jb4gVDCSnSW1M6Psh86FyrnUtLoG25i2XyO+4A== X-Google-Smtp-Source: AGHT+IFs3rF7qdC6qDVh1UlIglYJb6TlDzLJJh1E5AiP9qooVfg2sa8jDrKlU5aJlpJAZW62IUyepfBNdBy6JIOrW3Y= X-Received: by 2002:a17:90a:640b:b0:2c9:6a38:54e4 with SMTP id 98e67ed59e1d1-2d1e8078d59mr2382546a91.41.1723230265833; Fri, 09 Aug 2024 12:04:25 -0700 (PDT) MIME-Version: 1.0 References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240808085452.426702-1-juraj.linkes@pantheon.tech> <20240808085452.426702-6-juraj.linkes@pantheon.tech> In-Reply-To: <20240808085452.426702-6-juraj.linkes@pantheon.tech> From: Jeremy Spewock Date: Fri, 9 Aug 2024 15:04:14 -0400 Message-ID: Subject: Re: [PATCH v16 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 Looks good to me, I just had a few comments about copyright lines but the actual functionality seems like it's there to me: Reviewed-by: Jeremy Spewock On Thu, Aug 8, 2024 at 4:55=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 > --- /dev/null > +++ b/doc/api/dts/meson.build > @@ -0,0 +1,29 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(c) 2023 PANTHEON.tech s.r.o. Should this be 2023 or updated now that we're in 2024? Probably doesn't matter too much either way. > + > +sphinx =3D find_program('sphinx-build', required: get_option('enable_doc= s')) > +if not sphinx.found() > + subdir_done() > +endif > + > +python_ver_satisfied =3D run_command(get_dts_runtime_deps, check: false)= .returncode() > +if python_ver_satisfied !=3D 0 > + subdir_done() > +endif > + > +extra_sphinx_args =3D ['-E', '-c', join_paths(doc_source_dir, 'guides')] > +if get_option('werror') > + extra_sphinx_args +=3D '-W' > +endif > + > +htmldir =3D join_paths(get_option('datadir'), 'doc', 'dpdk', 'dts') > +dts_api_html =3D custom_target('dts_api_html', > + output: 'html', > + command: [sphinx_wrapper, sphinx, meson.project_version(), > + meson.current_source_dir(), meson.current_build_dir(), extra= _sphinx_args], > + build_by_default: get_option('enable_docs'), > + install: get_option('enable_docs'), > + install_dir: htmldir) > + > +dts_doc_targets +=3D dts_api_html > +dts_doc_target_names +=3D 'DTS_API_HTML' > diff --git a/doc/api/meson.build b/doc/api/meson.build > index 5b50692df9..788129336b 100644 > --- a/doc/api/meson.build > +++ b/doc/api/meson.build > @@ -1,6 +1,18 @@ > # SPDX-License-Identifier: BSD-3-Clause > # Copyright(c) 2018 Luca Boccassi > Should you add your copyright to the top of this file now that you've also modified it? > +dts_doc_targets =3D [] > +dts_doc_target_names =3D [] > +subdir('dts') > + > +if dts_doc_targets.length() =3D=3D 0 > + dts_message =3D 'No DTS docs targets found' > +else > + dts_message =3D 'Building DTS docs:' > +endif > +run_target('dts-doc', command: [echo, dts_message, dts_doc_target_names]= , > + depends: dts_doc_targets) > + > doxygen =3D find_program('doxygen', required: get_option('enable_docs')) > > if not doxygen.found() > @@ -40,6 +52,7 @@ cdata.set('WARN_AS_ERROR', 'NO') > if get_option('werror') > cdata.set('WARN_AS_ERROR', 'YES') > endif > +cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.ht= ml')) > > # configure HTML Doxygen run > html_cdata =3D configuration_data() > diff --git a/doc/guides/conf.py b/doc/guides/conf.py > index 0f7ff5282d..d7f3030838 100644 > --- a/doc/guides/conf.py >