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 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 <dev@dpdk.org>; Mon, 3 Apr 2023 11:17:17 +0200 (CEST)
Received: by mail-ed1-f54.google.com with SMTP id er13so73521972edb.9
for <dev@dpdk.org>; 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?= <juraj.linkes@pantheon.tech>
Date: Mon, 3 Apr 2023 11:17:06 +0200
Message-ID: <CAOb5WZaBGE9j-BHDg8EHzLFAhEoxJaLrq5WMDHazZTrZ1rK69Q@mail.gmail.com>
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 <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
--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 <juraj.linkes@pa=
ntheon.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
> 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
<div dir=3D"ltr"><div>Hi Bruce, Thomas,<br></div><div><br></div><div>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).</div><div><br></div><div>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?<br></div><div><br></div><div>Thanks,</div><div>Jur=
aj<br></div><br><div class=3D"gmail_quote"><div dir=3D"ltr" class=3D"gmail_=
attr">On Thu, Mar 23, 2023 at 11:40=E2=80=AFAM Juraj Linke=C5=A1 <juraj.=
linkes@pantheon.tech> wrote:<br></div><blockquote class=3D"gmail_quote" =
style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);pa=
dding-left:1ex">Augment the meson build system with dts api generation. The=
api docs are<br>
generated from Python docstrings in DTS using Sphinx. The format of<br>
choice is the Google format [0].<br>
<br>
The guide html sphinx configuration is used to preserve the same style.<br>
<br>
The build requires the same Python version and dependencies as DTS,<br>
because Sphinx imports the Python modules. Dependencies are installed<br>
using Poetry from the dts directory:<br>
<br>
poetry install --with docs<br>
<br>
After installing, enter the Poetry shell:<br>
<br>
poetry shell<br>
<br>
And then run the build:<br>
ninja -C <meson_build_dir> doc<br>
<br>
There's only one properly documented module that serves as a<br>
demonstration of the style - framework.testbed_model.node.<br>
<br>
I didn't figure out how to separate dts build from the rest of the docs=
,<br>
which I think is required because of the different dependencies.<br>
I thought the enable_docs option would do this, so I added<br>
enable_dts_docs, but it doesn't seem to be working. Requesting comment<=
br>
on this.<br>
<br>
[0] <a href=3D"https://google.github.io/styleguide/pyguide.html#s3.8.4-comm=
ents-in-classes" rel=3D"noreferrer" target=3D"_blank">https://google.github=
.io/styleguide/pyguide.html#s3.8.4-comments-in-classes</a><br>
<br>
Juraj Linke=C5=A1 (4):<br>
=C2=A0 dts: code adjustments for sphinx<br>
=C2=A0 dts: add doc generation dependencies<br>
=C2=A0 dts: add doc generation<br>
=C2=A0 dts: format docstrigs to google format<br>
<br>
=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 +<br>
=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 +-<br>
=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 +<br>
=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 +<br>
=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 =
-<br>
=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 +<br>
=C2=A0dts/framework/config/__init__.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =
=C2=A0 =C2=A0 |=C2=A0 11 +<br>
=C2=A0.../{testbed_model/hw =3D> config}/cpu.py=C2=A0 =C2=A0 =C2=A0 =C2=
=A0|=C2=A0 13 +<br>
=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 +-<br>
=C2=A0dts/framework/remote_session/__init__.py=C2=A0 =C2=A0 =C2=A0 |=C2=A0 =
=C2=A03 +-<br>
=C2=A0dts/framework/remote_session/linux_session.py |=C2=A0 =C2=A02 +-<br>
=C2=A0dts/framework/remote_session/os_session.py=C2=A0 =C2=A0 |=C2=A0 12 +-=
<br>
=C2=A0.../remote_session/remote/__init__.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=
=A0|=C2=A0 16 -<br>
=C2=A0.../{remote =3D> }/remote_session.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =
=C2=A0 =C2=A0 |=C2=A0 =C2=A00<br>
=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<br>
=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 +-<br>
=C2=A0dts/framework/testbed_model/__init__.py=C2=A0 =C2=A0 =C2=A0 =C2=A0|=
=C2=A0 10 +-<br>
=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 ++--<br>
=C2=A0dts/framework/testbed_model/sut_node.py=C2=A0 =C2=A0 =C2=A0 =C2=A0|=
=C2=A0 =C2=A09 +-<br>
=C2=A0.../testbed_model/{hw =3D> }/virtual_device.py=C2=A0 |=C2=A0 =C2=
=A00<br>
=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 +-<br>
=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 ++<br=
>
=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 ++++++++++=
++++++--<br>
=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 +<br>
=C2=A0dts/tests/TestSuite_hello_world.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =
=C2=A0 |=C2=A0 =C2=A06 +-<br>
=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 +<br>
=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 +<br>
=C2=A028 files changed, 1027 insertions(+), 225 deletions(-)<br>
=C2=A0create mode 100644 dts/doc-index.rst<br>
=C2=A0rename dts/framework/{testbed_model/hw =3D> config}/cpu.py (95%)<b=
r>
=C2=A0delete mode 100644 dts/framework/remote_session/remote/__init__.py<br=
>
=C2=A0rename dts/framework/remote_session/{remote =3D> }/remote_session.=
py (100%)<br>
=C2=A0rename dts/framework/remote_session/{remote =3D> }/ssh_session.py =
(100%)<br>
=C2=A0delete mode 100644 dts/framework/testbed_model/hw/__init__.py<br>
=C2=A0rename dts/framework/testbed_model/{hw =3D> }/virtual_device.py (1=
00%)<br>
=C2=A0create mode 100644 dts/meson.build<br>
<br>
-- <br>
2.30.2<br>
<br>
</blockquote></div></div>
--0000000000007bec7b05f86b06fa--