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 858DB428AA; Mon, 3 Apr 2023 11:17:19 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 282BD40ED7; Mon, 3 Apr 2023 11:17:19 +0200 (CEST) Received: from mail-ed1-f54.google.com (mail-ed1-f54.google.com [209.85.208.54]) by mails.dpdk.org (Postfix) with ESMTP id F41E140A7E for ; Mon, 3 Apr 2023 11:17:17 +0200 (CEST) Received: by mail-ed1-f54.google.com with SMTP id er13so73521972edb.9 for ; Mon, 03 Apr 2023 02:17:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20210112.gappssmtp.com; s=20210112; t=1680513437; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=Pd84Mn58ePiE2oV3r19Iz8yfybDfOX9BLX1rNFCz7Kg=; b=dnQ1ESbPuKUG/VRZfInCP29Xy2uqGRL8gFtLCQiIT1src24nBpxJ7VT5aVf/h2fGLr EG4hRlYOS7b+u4iZ6fcprKfaBRCcbb5hMa7onD2d6EVxptXjIk6R7/j0T3s4nPaDhzB5 2ytlxa0h6YdPag2JSvTKUZG4mnsZLM4sATPKCMz/1vg5cqkky6iejXAUwS6jH2MOvjxH lxXxv2HNh994kRaA7HYdLFPNtCVOS+yOg3mA7TfoisahL49B1O80CnOsW48BBIm68m8K 6bk09OfKtGXhVDLyE8i+/aMketWiygkYT1SLnT6O+pQfuwEkC4lMZ/Qj2ppB2X6iiDw4 vssw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680513437; 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=Pd84Mn58ePiE2oV3r19Iz8yfybDfOX9BLX1rNFCz7Kg=; b=hl6zMtvZO0NOIIRKIhse7UfgjbpvL05wufWgIArFucHGaBqhw8TZuUCPUJALROgStW J6KiA1ETk3FLxIkzsSl5rI+QZ82xdJ7RokTGRwM0uxmvcCadlP1pqXtEJCVvCOFr+F3R Ht/sqCX1rvuRyDNuVo5H0DVUEtVb8qyXVPT/ixs4KqbBoM2WfkXlTTAbnd2oc9s3Qrg2 L2Rf7gln+YmeTxDeofmp5NateZmEqOLwkM4enY3g1aXVsi/Tb3xCSfSWpj+yIChhm9RA r7JCEIUMe6AQdNoG5oihwpiPraF+RPnEJu4Gxz4vyBGon9Lb8NfbGzd9GP1fmnRNlV97 ELAA== X-Gm-Message-State: AAQBX9dsccK49s0/wNqUjYLR0F5Z9JZBbrS+89ZB64OO19fJwC1ADDSV TP0zkj+LUMXCgM7PVLLyL2fQyK2svUPt1XEiWxa4DM5Ae4gT2iI6 X-Google-Smtp-Source: AKy350YOXGig8246rCeS6ZK4vffk42+ZHIdKUMeeIuKEs7U0YBTftWanqnfNW+19GhdlLrDexTkOZsZGuhRJ17BCO00= X-Received: by 2002:a17:906:a86:b0:933:f6e8:26d9 with SMTP id y6-20020a1709060a8600b00933f6e826d9mr18373705ejf.15.1680513437521; Mon, 03 Apr 2023 02:17:17 -0700 (PDT) MIME-Version: 1.0 References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> In-Reply-To: <20230323104040.484708-1-juraj.linkes@pantheon.tech> From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Mon, 3 Apr 2023 11:17:06 +0200 Message-ID: Subject: Re: [RFC PATCH v1 0/4] dts: add dts api docs To: bruce.richardson@intel.com Cc: dev@dpdk.org Content-Type: multipart/alternative; boundary="0000000000007bec7b05f86b06fa" 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 --0000000000007bec7b05f86b06fa Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi Bruce, Thomas, The meson integration is kinda all over the place. I wanted to use the existing conf.py Sphinx config file, but I also wanted to keep the docs separated (because of extra DTS api docs dependencies), so the various pieces are in different places (the config file in one place, meson code in dts directory and generated Sphinx docs are in a new directory in the api build dir, separate from the rest of the Sphinx html). The big thing here is that I didn't figure out how to separate the dts api build from the rest of the docs. I don't know how the -Denable_docs option is supposed to work. I wanted to use -Denable_dts_docs in the same fashion to decouple the builds, but it doesn't seem to work. Reading the code I think the original option doesn't actually do anything - does it work? How is it supposed to work? Thanks, Juraj On Thu, Mar 23, 2023 at 11:40=E2=80=AFAM Juraj Linke=C5=A1 wrote: > Augment the meson build system with dts api generation. The api docs are > generated from Python docstrings in DTS using Sphinx. The format of > choice is the Google format [0]. > > The guide html sphinx configuration is used to preserve the same style. > > The build requires the same Python version and dependencies as DTS, > because Sphinx imports the Python modules. Dependencies are installed > using Poetry from the dts directory: > > poetry install --with docs > > After installing, enter the Poetry shell: > > poetry shell > > And then run the build: > ninja -C doc > > There's only one properly documented module that serves as a > demonstration of the style - framework.testbed_model.node. > > I didn't figure out how to separate dts build from the rest of the docs, > which I think is required because of the different dependencies. > I thought the enable_docs option would do this, so I added > enable_dts_docs, but it doesn't seem to be working. Requesting comment > on this. > > [0] > https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in-class= es > > Juraj Linke=C5=A1 (4): > dts: code adjustments for sphinx > dts: add doc generation dependencies > dts: add doc generation > dts: format docstrigs to google format > > doc/api/meson.build | 1 + > doc/guides/conf.py | 22 +- > doc/guides/meson.build | 1 + > doc/guides/tools/dts.rst | 29 + > doc/meson.build | 5 - > dts/doc-index.rst | 20 + > dts/framework/config/__init__.py | 11 + > .../{testbed_model/hw =3D> config}/cpu.py | 13 + > dts/framework/dts.py | 8 +- > dts/framework/remote_session/__init__.py | 3 +- > dts/framework/remote_session/linux_session.py | 2 +- > dts/framework/remote_session/os_session.py | 12 +- > .../remote_session/remote/__init__.py | 16 - > .../{remote =3D> }/remote_session.py | 0 > .../{remote =3D> }/ssh_session.py | 0 > dts/framework/settings.py | 55 +- > dts/framework/testbed_model/__init__.py | 10 +- > dts/framework/testbed_model/hw/__init__.py | 27 - > dts/framework/testbed_model/node.py | 164 ++-- > dts/framework/testbed_model/sut_node.py | 9 +- > .../testbed_model/{hw =3D> }/virtual_device.py | 0 > dts/main.py | 3 +- > dts/meson.build | 50 ++ > dts/poetry.lock | 770 ++++++++++++++++-- > dts/pyproject.toml | 7 + > dts/tests/TestSuite_hello_world.py | 6 +- > meson.build | 6 + > meson_options.txt | 2 + > 28 files changed, 1027 insertions(+), 225 deletions(-) > create mode 100644 dts/doc-index.rst > rename dts/framework/{testbed_model/hw =3D> config}/cpu.py (95%) > delete mode 100644 dts/framework/remote_session/remote/__init__.py > rename dts/framework/remote_session/{remote =3D> }/remote_session.py (10= 0%) > rename dts/framework/remote_session/{remote =3D> }/ssh_session.py (100%) > delete mode 100644 dts/framework/testbed_model/hw/__init__.py > rename dts/framework/testbed_model/{hw =3D> }/virtual_device.py (100%) > create mode 100644 dts/meson.build > > -- > 2.30.2 > > --0000000000007bec7b05f86b06fa Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Bruce, Thomas,

The me= son integration is kinda all over the place. I wanted to use the existing c= onf.py Sphinx config file, but I also wanted to keep the docs separated (be= cause of extra DTS api docs dependencies), so the various pieces are in dif= ferent places (the config file in one place, meson code in dts directory an= d generated Sphinx docs are in a new directory in the api build dir, separa= te from the rest of the Sphinx html).

The big thin= g here is that I didn't figure out how to separate the dts api build fr= om the rest of the docs. I don't know how the -Denable_docs option is s= upposed to work. I wanted to use -Denable_dts_docs in the same fashion to d= ecouple the builds, but it doesn't seem to work. Reading the code I thi= nk the original option doesn't actually do anything - does it work? How= is it supposed to work?

Thanks,
Jur= aj

On Thu, Mar 23, 2023 at 11:40=E2=80=AFAM Juraj Linke=C5=A1 <juraj.= linkes@pantheon.tech> wrote:
Augment the meson build system with dts api generation. The= api docs are
generated from Python docstrings in DTS using Sphinx. The format of
choice is the Google format [0].

The guide html sphinx configuration is used to preserve the same style.

The build requires the same Python version and dependencies as DTS,
because Sphinx imports the Python modules. Dependencies are installed
using Poetry from the dts directory:

poetry install --with docs

After installing, enter the Poetry shell:

poetry shell

And then run the build:
ninja -C <meson_build_dir> doc

There's only one properly documented module that serves as a
demonstration of the style - framework.testbed_model.node.

I didn't figure out how to separate dts build from the rest of the docs= ,
which I think is required because of the different dependencies.
I thought the enable_docs option would do this, so I added
enable_dts_docs, but it doesn't seem to be working. Requesting comment<= br> on this.

[0] https://google.github= .io/styleguide/pyguide.html#s3.8.4-comments-in-classes

Juraj Linke=C5=A1 (4):
=C2=A0 dts: code adjustments for sphinx
=C2=A0 dts: add doc generation dependencies
=C2=A0 dts: add doc generation
=C2=A0 dts: format docstrigs to google format

=C2=A0doc/api/meson.build=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 =C2=A01 +
=C2=A0doc/guides/conf.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2=A0 22 +-
=C2=A0doc/guides/meson.build=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2=A0 =C2=A01 +
=C2=A0doc/guides/tools/dts.rst=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2=A0 29 +
=C2=A0doc/meson.build=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 =C2=A05 = -
=C2=A0dts/doc-index.rst=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 20 +
=C2=A0dts/framework/config/__init__.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 |=C2=A0 11 +
=C2=A0.../{testbed_model/hw =3D> config}/cpu.py=C2=A0 =C2=A0 =C2=A0 =C2= =A0|=C2=A0 13 +
=C2=A0dts/framework/dts.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2=A0 =C2=A08 +-
=C2=A0dts/framework/remote_session/__init__.py=C2=A0 =C2=A0 =C2=A0 |=C2=A0 = =C2=A03 +-
=C2=A0dts/framework/remote_session/linux_session.py |=C2=A0 =C2=A02 +-
=C2=A0dts/framework/remote_session/os_session.py=C2=A0 =C2=A0 |=C2=A0 12 +-=
=C2=A0.../remote_session/remote/__init__.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0|=C2=A0 16 -
=C2=A0.../{remote =3D> }/remote_session.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 |=C2=A0 =C2=A00
=C2=A0.../{remote =3D> }/ssh_session.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 =C2=A00
=C2=A0dts/framework/settings.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 55 +-
=C2=A0dts/framework/testbed_model/__init__.py=C2=A0 =C2=A0 =C2=A0 =C2=A0|= =C2=A0 10 +-
=C2=A0dts/framework/testbed_model/hw/__init__.py=C2=A0 =C2=A0 |=C2=A0 27 -<= br> =C2=A0dts/framework/testbed_model/node.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= =C2=A0| 164 ++--
=C2=A0dts/framework/testbed_model/sut_node.py=C2=A0 =C2=A0 =C2=A0 =C2=A0|= =C2=A0 =C2=A09 +-
=C2=A0.../testbed_model/{hw =3D> }/virtual_device.py=C2=A0 |=C2=A0 =C2= =A00
=C2=A0dts/main.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2= =A0 =C2=A03 +-
=C2=A0dts/meson.build=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 50 ++ =C2=A0dts/poetry.lock=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| 770 ++++++++++= ++++++--
=C2=A0dts/pyproject.toml=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2=A0 =C2=A07 +
=C2=A0dts/tests/TestSuite_hello_world.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 |=C2=A0 =C2=A06 +-
=C2=A0meson.build=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2= =A0 =C2=A06 +
=C2=A0meson_options.txt=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 =C2=A02 +
=C2=A028 files changed, 1027 insertions(+), 225 deletions(-)
=C2=A0create mode 100644 dts/doc-index.rst
=C2=A0rename dts/framework/{testbed_model/hw =3D> config}/cpu.py (95%) =C2=A0delete mode 100644 dts/framework/remote_session/remote/__init__.py =C2=A0rename dts/framework/remote_session/{remote =3D> }/remote_session.= py (100%)
=C2=A0rename dts/framework/remote_session/{remote =3D> }/ssh_session.py = (100%)
=C2=A0delete mode 100644 dts/framework/testbed_model/hw/__init__.py
=C2=A0rename dts/framework/testbed_model/{hw =3D> }/virtual_device.py (1= 00%)
=C2=A0create mode 100644 dts/meson.build

--
2.30.2

--0000000000007bec7b05f86b06fa--