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 AD48442A6B; Fri, 5 May 2023 09:54:04 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5365C410EA; Fri, 5 May 2023 09:54:04 +0200 (CEST) Received: from mail-ej1-f43.google.com (mail-ej1-f43.google.com [209.85.218.43]) by mails.dpdk.org (Postfix) with ESMTP id 2103D406B6 for ; Fri, 5 May 2023 09:54:02 +0200 (CEST) Received: by mail-ej1-f43.google.com with SMTP id a640c23a62f3a-957dbae98b4so218180566b.1 for ; Fri, 05 May 2023 00:54:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683273242; x=1685865242; 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=BnlVXyfW4kRWdfed7jvcAqf8vrYjK1e+NRK55U0/6Oc=; b=yI18QVfgo06DqYz+8wofynPc6BAbAfOFQwh66vGvuoF3HfXoJzVVnHDCbr3n2lQ6Zj N18eK4n9YMBsIKN29oHytm8lBQzIrYE2LKuPu1846fN7tKQKis0WH2wSvGgO3FGhB7sl nu8IETrm1R3GvINm4q+3scnZnL+kKNdPi57vHHsVxonj+R4AAP4t+GX1ZLXFFe02zwwT FeNuWXURhqZTjJCPdXqflsjKZX4kwmfHkGvB1sdBRofTN4+hnmWVsBvgWs3V35nam8Cs BchS/05U7OkGsI8t5wfOpF+6SBNu1m8U24Gh2SshRPWpSfPlps071yIzuWqYnUX2yYTZ yBdw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683273242; x=1685865242; 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=BnlVXyfW4kRWdfed7jvcAqf8vrYjK1e+NRK55U0/6Oc=; b=hbhlcJbOgvJIWcrx4m/y7mZZSxYJcaVBEO0HuVr1ZhQJUxswVTZEPw5qo9jcdQFPhU vOBoe8S+2lTDklqSpfvR7AaO6WxY2Wol+j+btQmor6vCy3uOPP6KQS8rVVsoYMAy+fCx 5Q82+WLb4h1/VW2bbSZthRgLT79t54p2w3Rx9n+TAkYmNjRxmnoko3vSBYBZUWhKHwq7 QbzKAbWUhfimdyryQj/j3Dd7ISwJ+1Rqmk6hTbIWFRR757JIjiY4YorEEC6jTUgUOta2 ukFfxQP1PrYqaFiQGQldevcn5/H3kelbO3jzTWHp/TeBitUZ7Fl4iKOW70AikN7zDX8v lacQ== X-Gm-Message-State: AC+VfDymL3nR1uoWCk8dAIfT75vL/XCWJStpa5D8Q5qMNlCakLXJzdJj NPMhM5S6DZobZViw9Bs9IORfIFfRLCu10SMj4L5VRQ== X-Google-Smtp-Source: ACHHUZ6QH/UKz3eEXHdYIpJajsc2chrExlBCIV3je7dbrna4GNvoHEQ3jsHg6o3j7/H5Gj/1nxm9Wn216evWmc8zC0Q= X-Received: by 2002:a17:907:5c6:b0:939:e870:2b37 with SMTP id wg6-20020a17090705c600b00939e8702b37mr358194ejb.70.1683273241925; Fri, 05 May 2023 00:54:01 -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: Fri, 5 May 2023 09:53:50 +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 Thu, May 4, 2023 at 2:45=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 already > > used in DPDK. The configuration is kept the same to preserve the style. > > > > Sphinx generates the documentation from Python docstrings. The docstrin= g > > 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 import the > > code. > > * Also the same Python packages as DTS, for the same reason. > > > > [0] https://google.github.io/styleguide/pyguide.html#38-comments-and-do= cstrings > > > > 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_d= ts_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-inheritance', > > + sphinx_apidoc, '--append-syspath', '--force', > > + '--module-first', '--separate', > > + '--doc-project', 'DTS', '-V', meson.project_version(), > > + '-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' > > + > > +cp =3D find_program('cp', required: get_option('enable_docs')) > > This should probably be "enable_dts_docs" > Right, I overlooked that. What do you think of the implementation in general?