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 934EB43F4B;
	Mon, 29 Apr 2024 16:12:21 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 76D48402B3;
	Mon, 29 Apr 2024 16:12:21 +0200 (CEST)
Received: from mail-oi1-f176.google.com (mail-oi1-f176.google.com
 [209.85.167.176])
 by mails.dpdk.org (Postfix) with ESMTP id 1F32C402A3
 for <dev@dpdk.org>; Mon, 29 Apr 2024 16:12:20 +0200 (CEST)
Received: by mail-oi1-f176.google.com with SMTP id
 5614622812f47-3c8644aa3feso773137b6e.1
 for <dev@dpdk.org>; Mon, 29 Apr 2024 07:12:20 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=iol.unh.edu; s=unh-iol; t=1714399939; x=1715004739; darn=dpdk.org;
 h=cc:to:subject:message-id:date:from:in-reply-to:references
 :mime-version:from:to:cc:subject:date:message-id:reply-to;
 bh=uhk9M0i1kyjh+E0V2ewQklqUlc81mt2wVQV0dEiY4x4=;
 b=A0sUJh5QdMC47O8JI2uxNH+x4YyKj2WXMvwJuIoXfPRgMsUrBwwtafvSZyHOpJb3ze
 cudsRZ9Cfn5j+mMkih0mclTQ0d8/DQe29hdPNmcn+wmD4Jsi/KCBes7nVG9zPxlfM9SL
 uGraFlThmFhsSc1qByk4nVerw52S7iMQrUcfA=
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1714399939; x=1715004739;
 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=uhk9M0i1kyjh+E0V2ewQklqUlc81mt2wVQV0dEiY4x4=;
 b=GoOIoDHjKAEVd6gkjWjqcm2Fbqx9fgFijndkRJIL3L06KjNOsGU8oVDazRexqODnMP
 629KHpa4R4k7MFSwoZ2YcxosgGv6c4rdGHpditvDpWrln5nS2y7j2+UBLn6Yc/Gd/eMs
 T1x4tzPICW9sE3ujvtgtMpDdzmutwGSCuktp58IyFw6YEHpu0+MprPwXWMDxhSPLNMEb
 uFqwucagfDNdaIEBUaBz2e74VJ7yvt9D60ATrt0DTXhCST2OByIyyyNEDuoQvY+8rfLe
 72tB6GHLGWAIZqgXp4oibfShft4g5WGKB6FJh1ENHWNa2MFRnnCdej5jzqVE74T3nHBP
 FStw==
X-Forwarded-Encrypted: i=1;
 AJvYcCV+4bXZCaP4GzxwCJwBOoQadsL4hP6V1Pje4w1C642KYYqMtnVo2qggpKsfMAceql+ZD1zMXz1hNQS/pZw=
X-Gm-Message-State: AOJu0Yw1bh5o1vtGhbFWnwWgKvMQzSrJ9NXfeZMheybays6NkTuzgzIp
 TzwDpM97BdUdDsa56Ce6xhb2SCBDEFWncNbqmbKCsBq0Smu/8iadYsVDm38qnrnYlB9j+b9xEjQ
 9Q+BZeuunkP523rk5QJlco8K4QUiKSqm24MPUSQ==
X-Google-Smtp-Source: AGHT+IErCvPDPYPae9htSyJtK+fOiEWP6088UlwGIN/4TxyefO33MW9jxirEZXTRnq3K3h5H/hOvkROEc0NowTpWUV0=
X-Received: by 2002:a05:6871:340a:b0:23b:360d:4549 with SMTP id
 nh10-20020a056871340a00b0023b360d4549mr11508399oac.38.1714399939449; Mon, 29
 Apr 2024 07:12:19 -0700 (PDT)
MIME-Version: 1.0
References: <20231115133606.42081-1-juraj.linkes@pantheon.tech>
 <20240412101405.94377-1-juraj.linkes@pantheon.tech>
 <CAAA20UQ=e44Q9ygH3roe_Okg2JnQBBbMbOnRZ9_U0H-_DyEugA@mail.gmail.com>
In-Reply-To: <CAAA20UQ=e44Q9ygH3roe_Okg2JnQBBbMbOnRZ9_U0H-_DyEugA@mail.gmail.com>
From: Patrick Robb <probb@iol.unh.edu>
Date: Mon, 29 Apr 2024 10:12:08 -0400
Message-ID: <CAJvnSUCO1WQygKEB1W36ADfGFzGf9WxUyhesRgLq5j8RvTgNjg@mail.gmail.com>
Subject: Re: [PATCH v4 0/3] dts: API docs generation
To: Jeremy Spewock <jspewock@iol.unh.edu>
Cc: =?UTF-8?Q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>, 
 thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, 
 paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu, 
 dev@dpdk.org
Content-Type: multipart/alternative; boundary="00000000000064ef6e06173cd73b"
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

--00000000000064ef6e06173cd73b
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Mon, Apr 29, 2024 at 9:49=E2=80=AFAM Jeremy Spewock <jspewock@iol.unh.ed=
u> wrote:

> <snip>
> > The patchset contains the .rst sources which Sphinx uses to generate th=
e
> > html pages. These were first generated with the sphinx-apidoc utility
> > and modified to provide a better look. The documentation just doesn't
> > look that good without the modifications and there isn't enough
> > configuration options to achieve that without manual changes to the .rs=
t
> > files. This introduces extra maintenance which involves adding new .rst
> > files when a new Python module is added or changing the .rst structure
> > if the Python directory/file structure is changed (moved, renamed
> > files). This small maintenance burden is outweighed by the flexibility
> > afforded by the ability to make manual changes to the .rst files.
> >
> > We can merge this patch when:
> > 1. We agree on the approach with manually modifying the files.
> > This approach is, in my opinion, much better than just generating the
> > .rst files every time,
>
> +1 for manually modifying .rst files. The .rst files are very simple,
> and I think the added flexibility to change headers or tweak things as
> needed is a big benefit over just auto-generating and not having as
> much control. Additionally, if it just so happens that the
> auto-generated file looks fine and the developer doesn't want to make
> changes, they can still just generate it themselves and it fits right
> in, so this approach still works with the other regardless.
>
> +1

--00000000000064ef6e06173cd73b
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=3D"gmail_quote">=
<div dir=3D"ltr" class=3D"gmail_attr">On Mon, Apr 29, 2024 at 9:49=E2=80=AF=
AM Jeremy Spewock &lt;<a href=3D"mailto:jspewock@iol.unh.edu">jspewock@iol.=
unh.edu</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"=
margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-lef=
t:1ex">&lt;snip&gt;<br>
&gt; The patchset contains the .rst sources which Sphinx uses to generate t=
he<br>
&gt; html pages. These were first generated with the sphinx-apidoc utility<=
br>
&gt; and modified to provide a better look. The documentation just doesn&#3=
9;t<br>
&gt; look that good without the modifications and there isn&#39;t enough<br=
>
&gt; configuration options to achieve that without manual changes to the .r=
st<br>
&gt; files. This introduces extra maintenance which involves adding new .rs=
t<br>
&gt; files when a new Python module is added or changing the .rst structure=
<br>
&gt; if the Python directory/file structure is changed (moved, renamed<br>
&gt; files). This small maintenance burden is outweighed by the flexibility=
<br>
&gt; afforded by the ability to make manual changes to the .rst files.<br>
&gt;<br>
&gt; We can merge this patch when:<br>
&gt; 1. We agree on the approach with manually modifying the files.<br>
&gt; This approach is, in my opinion, much better than just generating the<=
br>
&gt; .rst files every time,<br>
<br>
+1 for manually modifying .rst files. The .rst files are very simple,<br>
and I think the added flexibility to change headers or tweak things as<br>
needed is a big benefit over just auto-generating and not having as<br>
much control. Additionally, if it just so happens that the<br>
auto-generated file looks fine and the developer doesn&#39;t want to make<b=
r>
changes, they can still just generate it themselves and it fits right<br>
in, so this approach still works with the other regardless.<br>
<br></blockquote><div>+1=C2=A0</div></div></div>

--00000000000064ef6e06173cd73b--