Re: [PATCH] Documentation: Document the Netlink spec

[Breno Leitao <leitao@debian.org>]

On Thu, Nov 09, 2023 at 07:12:38AM -0700, Jonathan Corbet wrote:
> Donald Hunter <donald.hunter@gmail.com> writes:
> 
> > Jonathan Corbet <corbet@lwn.net> writes:
> >> I do have to wonder, though, whether a sphinx extension is the right way
> >> to solve this problem.  You're essentially implementing a filter that
> >> turns one YAML file into one RST file; might it be better to keep that
> >> outside of sphinx as a standalone script, invoked by the Makefile?
> >>
> >> Note that I'm asking because I wonder, I'm not saying I would block an
> >> extension-based implementation.
> >
> > +1 to this. The .rst generation can then be easily tested independently
> > of the doc build and the stub files could be avoided.
> >
> > Just a note that last year you offered the opposite guidance:
> >
> > https://lore.kernel.org/linux-doc/87tu4zsfse.fsf@meer.lwn.net/
> 
> Heh ... I totally forgot about that whole discussion ...
> 
> > If the preference now is for standalone scripts invoked by the Makefile
> > then this previous patch might be useful:
> >
> > https://lore.kernel.org/linux-doc/20220922115257.99815-2-donald.hunter@gmail.com/
> >
> > It would be good to document the preferred approach to this kind of doc
> > extension and I'd be happy to contribute an 'Extensions' section for
> > contributing.rst in the doc-guide.
> 
> I think it will vary depending on what we're trying to do, and I think
> we're still working it out - part of why I expressed some uncertainty
> this time around.
> 
> For something like the kernel-doc or automarkup, where we are modifying
> existing documents, an extension is the only way to go.  In this case,
> where we are creating new RST files from whole cloth, it's not so clear
> to me.  My feeling (this week at least ;) is that doing it as an
> extension makes things more complicated without a lot of benefit.

One way or another works for me. Given my experience with both ways, let
me share the advantages of boths so we can understand the trade-offs
better:

Sphinx extension advantages:
===========================

 1) Keep "extensions" uniform and organized, written in the same
 framework/language (python), using the same enry point, output, etc.

 2) Easy to cross reference objects in the whole documentation (not done
 in this patchset)

 3) Same dependencies for all "documentation". I.e, you don't need a
 dependency (as in python pip requirements.txt) for every "parser"
 script.

 4) Already being used in our infrastructure.


One-off parser advantages:
=========================

 1) Total flexibility. You can write the parser in any language.

 2) Easier and faster to interate and debug.

 3) No need to have a rst stub for every file (as in this patchset).
 This is a sphinx limitation right now, and *might* go away in the
 future.

 4) Less dependent of sphinx project.

> FWIW, if something like this is done as a makefile change, I'd do it a
> bit differently than your linked patch above.  Rather than replicate the
> command through the file, I'd just add a new target:
> 
>   netlink_specs:
>   	.../scripts/gen-netlink-rst
> 
>   htmldocs: netlink_specs
>   	existing stuff here
> 
> But that's a detail.

For that, we can't use a sphinx extension, since there is no way (as I
understood) from one rst to generate multiple rst.