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 9A5B742AC9; Wed, 10 May 2023 14:19:19 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 2471E406B6; Wed, 10 May 2023 14:19:19 +0200 (CEST) Received: from mail-ed1-f42.google.com (mail-ed1-f42.google.com [209.85.208.42]) by mails.dpdk.org (Postfix) with ESMTP id 1337440697 for ; Wed, 10 May 2023 14:19:18 +0200 (CEST) Received: by mail-ed1-f42.google.com with SMTP id 4fb4d7f45d1cf-50bc0117683so12789521a12.1 for ; Wed, 10 May 2023 05:19:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683721157; x=1686313157; 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=DVxYHKE2HvLc7mPY0xSZ6Yv7sYrzAF9kHL4Yz9cCN1Q=; b=rGccYU6Yn/A0Hj+gzm3RWis1TJk5I+J54QLL6RfJlYEr1wjED8l5dXzBIqQh3A96GJ YJMpfv5BQoOaLySBbX4Cjb/Ofz/0/VKXSgMRmNGsQJAoL7rOzzdOhf1Ui8T90f49czOH 4I/dA52GCTPA2VG04rPb6s99vZ4rC0CL8E3DMrAbOdscOZfU5APnbbNGowoZ8SbCBM1u 4lX3qadn7x6NIsuAfynATVzEOF4AExHF+wH+ZYYo1DTCAoqxfTopde/danhYtdEKSvlW EFnsqyIntpqU7P+v54cvrjKhtJT01TgCeVaMR6Cb+EfqQ1yoIUO4QqG+gSNzWSapKbBP gIVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683721157; x=1686313157; 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=DVxYHKE2HvLc7mPY0xSZ6Yv7sYrzAF9kHL4Yz9cCN1Q=; b=cN9CUUfWFG3tLuC6DyXL4vLnzPAYHTFfrJYPE+hwTRznVyIL2Ln5tBm5HK8ICkzaxg kMHEV8xCCXL/d1yiC2hgQ6/VMqlVPCKxrhUlKZEvhHKRTafSQIO9+HBIeLjmtmTUeOa7 21727AdBl5sg2NILmb5m6Y/y9ZJkl7Kd+UOECpc3ga1ZPvN/bpyyibxaI5hl1Wri2swX +iuGyHzQut9mJjrDmoIw43B+LKR/ubiGt8xXuKVm2+KPEXSmZKWsBIZy05zkuMN86WGR kkv4qrd9pEzaqtrYNCBREf9T413aoA0/c5+8JgPxXnrtobL2DOuGvKuvWv3T+ajTYZWq 6fbA== X-Gm-Message-State: AC+VfDwRompdNUxawErRW470mmOVwBteNo9foo8nOVQKr6ejhDhbwupY 14/+dYg3olsQnLTmS/4eHMZ9T+SfsQPgAfWC3s0PxQ== X-Google-Smtp-Source: ACHHUZ7yptyMuuM62lkEjJXlGwdghbMZUSKgViKGUbL7Z6Mvif9Sqjv1hZXTIUOpjE6eXH5QddID4HrRW1ZGEBWjRgk= X-Received: by 2002:aa7:cb87:0:b0:50d:ddc6:ceed with SMTP id r7-20020aa7cb87000000b0050dddc6ceedmr856874edt.33.1683721157603; Wed, 10 May 2023 05:19:17 -0700 (PDT) MIME-Version: 1.0 References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> <20230504123749.1417259-1-juraj.linkes@pantheon.tech> <20230504123749.1417259-4-juraj.linkes@pantheon.tech> In-Reply-To: From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Wed, 10 May 2023 14:19:06 +0200 Message-ID: Subject: Re: [RFC PATCH v2 3/4] dts: add doc generation To: Bruce Richardson Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, lijuan.tu@intel.com, wathsala.vithanage@arm.com, jspewock@iol.unh.edu, probb@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 Tue, May 9, 2023 at 11:40=E2=80=AFAM Bruce Richardson wrote: > > On Tue, May 09, 2023 at 11:23:50AM +0200, Juraj Linke=C5=A1 wrote: > > On Fri, May 5, 2023 at 3:29=E2=80=AFPM Bruce Richardson > > wrote: > > > > > > On Fri, May 05, 2023 at 01:13:34PM +0200, Juraj Linke=C5=A1 wrote: > > > > On Fri, May 5, 2023 at 12:57=E2=80=AFPM Bruce Richardson > > > > wrote: > > > > > > > > > > On Thu, May 04, 2023 at 02:37:48PM +0200, Juraj Linke=C5=A1 wrote= : > > > > > > The tool used to generate developer docs is sphinx, which is al= ready > > > > > > used in DPDK. The configuration is kept the same to preserve th= e style. > > > > > > > > > > > > Sphinx generates the documentation from Python docstrings. The = docstring > > > > > > format most suitable for DTS seems to be the Google format [0] = which > > > > > > requires the sphinx.ext.napoleon extension. > > > > > > > > > > > > There are two requirements for building DTS docs: > > > > > > * The same Python version as DTS or higher, because Sphinx impo= rt the > > > > > > code. > > > > > > * Also the same Python packages as DTS, for the same reason. > > > > > > > > > > > > [0] https://google.github.io/styleguide/pyguide.html#38-comment= s-and-docstrings > > > > > > > > > > > > Signed-off-by: Juraj Linke=C5=A1 > > > > > > --- > > > > > > doc/api/meson.build | 1 + > > > > > > doc/guides/conf.py | 22 ++++++++++++++---- > > > > > > doc/guides/meson.build | 1 + > > > > > > doc/guides/tools/dts.rst | 29 +++++++++++++++++++++++ > > > > > > dts/doc/doc-index.rst | 20 ++++++++++++++++ > > > > > > dts/doc/meson.build | 50 ++++++++++++++++++++++++++++++++= ++++++++ > > > > > > dts/meson.build | 16 +++++++++++++ > > > > > > meson.build | 1 + > > > > > > meson_options.txt | 2 ++ > > > > > > 9 files changed, 137 insertions(+), 5 deletions(-) > > > > > > create mode 100644 dts/doc/doc-index.rst > > > > > > create mode 100644 dts/doc/meson.build > > > > > > create mode 100644 dts/meson.build > > > > > > > > > > > > > > > > > > > > > > diff --git a/dts/doc/meson.build b/dts/doc/meson.build > > > > > > new file mode 100644 > > > > > > index 0000000000..db2bb0bed9 > > > > > > --- /dev/null > > > > > > +++ b/dts/doc/meson.build > > > > > > @@ -0,0 +1,50 @@ > > > > > > +# SPDX-License-Identifier: BSD-3-Clause > > > > > > +# Copyright(c) 2023 PANTHEON.tech s.r.o. > > > > > > + > > > > > > +sphinx =3D find_program('sphinx-build', required: get_option('= enable_dts_docs')) > > > > > > +sphinx_apidoc =3D find_program('sphinx-apidoc', required: get_= option('enable_dts_docs')) > > > > > > + > > > > > > +if sphinx.found() and sphinx_apidoc.found() > > > > > > +endif > > > > > > + > > > > > > +dts_api_framework_dir =3D join_paths(dts_dir, 'framework') > > > > > > +dts_api_build_dir =3D join_paths(doc_api_build_dir, 'dts') > > > > > > +dts_api_src =3D custom_target('dts_api_src', > > > > > > + output: 'modules.rst', > > > > > > + command: ['SPHINX_APIDOC_OPTIONS=3Dmembers,show-inheri= tance', > > > > > > > > > > This gives errors when I try to configure a build, even without d= ocs > > > > > enabled. > > > > > > > > > > ~/dpdk.org$ meson setup build-test > > > > > The Meson build system > > > > > Version: 1.0.1 > > > > > Source dir: /home/bruce/dpdk.org > > > > > ... > > > > > Program sphinx-build found: YES (/usr/bin/sphinx-build) > > > > > Program sphinx-build found: YES (/usr/bin/sphinx-build) > > > > > Program sphinx-apidoc found: YES (/usr/bin/sphinx-apidoc) > > > > > > > > > > dts/doc/meson.build:12:0: ERROR: Program 'SPHINX_APIDOC_O= PTIONS=3Dmembers,show-inheritance' not found or not executable > > > > > > > > > > A full log can be found at /home/bruce/dpdk.org/build-tes= t/meson-logs/meson-log.txt > > > > > > > > > > Assuming these need to be set in the environment, I think you can= use the > > > > > "env" parameter to custom target instead. > > > > > > > > > > > > > I used meson 0.53.2 as that seemed to be the version I should targe= t > > > > (it's used in .ci/linux-setup.sh) which doesn't support the argumen= t > > > > (I originally wanted to use it, but they added it in 0.57.0). I did= n't > > > > see the error with 0.53.2. > > > > > > > > Which version should I target? 1.0.1? > > > > > > > > > > + sphinx_apidoc, '--append-syspath', '--force', > > > > > > + '--module-first', '--separate', > > > > > > + '--doc-project', 'DTS', '-V', meson.project_versio= n(), > > > > > > + '-o', dts_api_build_dir, > > > > > > + dts_api_framework_dir], > > > > > > + build_by_default: get_option('enable_dts_docs')) > > > > > > +doc_targets +=3D dts_api_src > > > > > > +doc_target_names +=3D 'DTS_API_sphinx_sources' > > > > > > + > > > > > > I didn't try with 0.53.2 - let me test that, see if the error goes aw= ay. We > > > may need different calls based on the meson version. > > > > > > Is there no other way to pass this data rather than via the environme= nt? > > > > > > > Certainly. For background, I wanted to do the same thing we do for > > DPDK_VERSION, but that would require adding an additional parameter to > > call-sphinx-build.py, which wouldn't be used by the other call of > > call-sphinx-build.py (the one that builds doc guides), so I skipped > > the parameter and set the env var before the call. > > > > There are a few options that come to mind: > > 1. Use the parameter. There are two sub-options here, either make the > > parameter positional and mandatory and then we'd have an awkward call > > that builds the guides or I could make it optional, but that would > > make the script a bit more complex (some argparse logic would be > > needed). > > 2. Hard-code the path into conf.py. > > 3. Have separate conf.py files. Maybe we could make this work with syml= inks. > > > > There could be something else. I like adding the optional parameter. I > > don't know the policy on buildtools script complexity so let me know > > what you think. > > > If the parameter would be just unused for the main doc build, and cause n= o > issues, I don't see why we can't just put it into the main conf.py file. = We > can add a comment explaining that it only applies for the DTS doc. Howeve= r, > option 1, with an extra optional parameter doesn't seem so bad to me > either. Using argparse in the build script doesn't seem like a problem > either, if it's necessary. Maybe others have other opinions, though. > I'll just submit the version with argparse and we'll see how it looks. > /Bruce