From: Jonathan Corbet <corbet@lwn•net>
To: Jani Nikula <jani.nikula@linux•intel.com>,
Breno Leitao <leitao@debian•org>,
kuba@kernel•org, "David S. Miller" <davem@davemloft•net>
Cc: linux-doc@vger•kernel.org, netdev@vger•kernel.org,
linux-kernel@vger•kernel.org, pabeni@redhat•com,
edumazet@google•com
Subject: Re: [PATCH v3] Documentation: Document each netlink family
Date: Tue, 30 Jan 2024 07:22:08 -0700 [thread overview]
Message-ID: <87jznqewa7.fsf@meer.lwn.net> (raw)
In-Reply-To: <874jevjgvo.fsf@intel.com>
Jani Nikula <jani.nikula@linux•intel.com> writes:
> On Tue, 21 Nov 2023, Breno Leitao <leitao@debian•org> wrote:
>> This is a simple script that parses the Netlink YAML spec files
>> (Documentation/netlink/specs/), and generates RST files to be rendered
>> in the Network -> Netlink Specification documentation page.
>
> First of all, my boilerplate complaint: All extra processing for Sphinx
> should really be done using Sphinx extensions instead of adding Makefile
> hacks. I don't think it's sustainable to keep adding this stuff. We
> chose Sphinx because it is extensible, and to avoid the Rube Goldberg
> machine that the previous documentation build system was.
So I feel like we've (me included) have kind of sent Breno around in
circles on this one. This *was* implemented as an extension once:
https://lore.kernel.org/netdev/20231103135622.250314-1-leitao@debian.org/
At that time it seemed too complex, and I thought that an external
script would lead to a simpler implementation overall. Perhaps I was
wrong.
I worry that a proliferation of extensions adds its own sort of
complexity and hazards - look at the things Vegard has fixed recently,
for example. Relatively few people can work in that environment, and
extensions can make our version-support troubles worse. So I'm not
fully sold on the idea that everything should be an extension,
especially if it can be expressed as a simple dependency and build step
in the makefile.
Some of the uglier makefile stuff we have is a different story...
Anyway, I apologize for my role in making this particular addition
harder than it needed to be. Perhaps, for the future, we should put
together and agree on a document (of all things) on how we think this
sort of functionality should be added.
Thanks,
jon
next prev parent reply other threads:[~2024-01-30 14:22 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-11-21 11:48 [PATCH v3] Documentation: Document each netlink family Breno Leitao
2023-11-21 16:15 ` Jakub Kicinski
2023-11-24 1:20 ` patchwork-bot+netdevbpf
2024-01-30 9:43 ` Jani Nikula
2024-01-30 14:22 ` Jonathan Corbet [this message]
2024-01-30 15:03 ` Jani Nikula
2024-01-30 16:06 ` Breno Leitao
2024-01-30 16:23 ` Vegard Nossum
2024-01-30 17:29 ` Breno Leitao
2024-02-09 14:47 ` Vegard Nossum
2024-02-09 23:20 ` Akira Yokosawa
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87jznqewa7.fsf@meer.lwn.net \
--to=corbet@lwn$(echo .)net \
--cc=davem@davemloft$(echo .)net \
--cc=edumazet@google$(echo .)com \
--cc=jani.nikula@linux$(echo .)intel.com \
--cc=kuba@kernel$(echo .)org \
--cc=leitao@debian$(echo .)org \
--cc=linux-doc@vger$(echo .)kernel.org \
--cc=linux-kernel@vger$(echo .)kernel.org \
--cc=netdev@vger$(echo .)kernel.org \
--cc=pabeni@redhat$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox