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 <<a href=3D"mailto:jspewock@iol.unh.edu">jspewock@iol.= unh.edu</a>> 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"><snip><br> > The patchset contains the .rst sources which Sphinx uses to generate t= he<br> > 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<br> > look that good without the modifications and there isn't enough<br= > > configuration options to achieve that without manual changes to the .r= st<br> > files. This introduces extra maintenance which involves adding new .rs= t<br> > files when a new Python module is added or changing the .rst structure= <br> > if the Python directory/file structure is changed (moved, renamed<br> > files). This small maintenance burden is outweighed by the flexibility= <br> > afforded by the ability to make manual changes to the .rst files.<br> ><br> > We can merge this patch when:<br> > 1. We agree on the approach with manually modifying the files.<br> > This approach is, in my opinion, much better than just generating the<= br> > .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'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--