On Tue, Jan 30, 2024 at 05:23:36PM +0100, Vegard Nossum wrote:

On 30/01/2024 17:06, Breno Leitao wrote:

quoted

On Tue, Jan 30, 2024 at 07:22:08AM -0700, Jonathan Corbet wrote:

quoted

Jani Nikula [off-list ref] writes:

quoted

On Tue, 21 Nov 2023, Breno Leitao [off-list ref] wrote:

quoted

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/ (local)

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 think you are correct. I personally _think_ that the external script
is better, mainly because it is self contained, thus, easier to
maintain.

From a cursory look at the two versions, the actual Python code to read
the YAML and write the reST is the same in both cases. (Breno, please
correct me if I'm wrong.)

You are correct. They are similar because Sphinx was not bringing much
value to what I was trying to do (or I was not able to explore all
Sphinx benefit - It was my very first Sphinx plug-in).

That said, the plug-in was basically a wrapper around "the Python code",
that was re-used for the one-off script. So, moving from one to another
was easy.