Re: [PATCH v3] Documentation: Document each netlink family

[Vegard Nossum]

On 30/01/2024 17:06, Breno Leitao wrote:
> On Tue, Jan 30, 2024 at 07:22:08AM -0700, Jonathan Corbet wrote:
> > Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> writes:
> >
> > > On Tue, 21 Nov 2023, Breno Leitao <leitao@xxxxxxxxxx> 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@xxxxxxxxxx/
> >
> > 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