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

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.)

It should be fairly easy to support both methods by moving most of the
code into a library and then having two thin wrappers around it, one
being a stand-alone command-line script and one being the Sphinx extension.

The stand-alone script could even be put directly in the library code,
just wrapped in "if __name__ == '__main__'".

A stand-alone script might be useful for debugging the output without
invoking the full sphinx-build machinery (i.e. basically having an easy
way to inspect and diff the output when making changes to the code).

Bottom line: This particular thing looks like a false dichotomy to me.

We should still fix the writing of .rst to $(srctree), though --
our use of parse-headers.pl seems to sidestep this by writing the
intermediate .rst output to Documentation/output/, I'll have to look a
bit more closely.


Vegard