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 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 ; Mon, 29 Apr 2024 16:12:20 +0200 (CEST) Received: by mail-oi1-f176.google.com with SMTP id 5614622812f47-3c8644aa3feso773137b6e.1 for ; 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> In-Reply-To: From: Patrick Robb Date: Mon, 29 Apr 2024 10:12:08 -0400 Message-ID: Subject: Re: [PATCH v4 0/3] dts: API docs generation To: Jeremy Spewock Cc: =?UTF-8?Q?Juraj_Linke=C5=A1?= , 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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 wrote: > > > 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


=
On Mon, Apr 29, 2024 at 9:49=E2=80=AF= AM Jeremy Spewock <jspewock@iol.= unh.edu> wrote:
<snip>
> The patchset contains the .rst sources which Sphinx uses to generate t= he
> html pages. These were first generated with the sphinx-apidoc utility<= br> > and modified to provide a better look. The documentation just doesn= 9;t
> look that good without the modifications and there isn't enough > configuration options to achieve that without manual changes to the .r= st
> files. This introduces extra maintenance which involves adding new .rs= t
> 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<= br> > .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=C2=A0
--00000000000064ef6e06173cd73b--