Re: [PATCH] Documentation: Document the Netlink spec

[Jonathan Corbet <corbet@lwn.net>]

Breno Leitao <leitao@debian.org> writes:

> This is a Sphinx extension that parses the Netlink YAML spec files
> (Documentation/netlink/specs/), and generates a rst file to be
> displayed into Documentation pages.
>
> Create a new Documentation/networking/netlink_spec page, and a sub-page
> for each Netlink spec that needs to be documented, such as ethtool,
> devlink, netdev, etc.
>
> Create a Sphinx directive extension that reads the YAML spec
> (located under Documentation/netlink/specs), parses it and returns a RST
> string that is inserted where the Sphinx directive was called.

So I finally had a chance to look a bit at this; I have a few
impressions.

First of all, if you put something silly into one of the YAML files, it
kills the whole docs build, which is ... not desirable:

> Exception occurred:
>   File "/usr/lib64/python3.11/site-packages/yaml/scanner.py", line 577, in fetch_value
>     raise ScannerError(None, None,
> yaml.scanner.ScannerError: mapping values are not allowed here
>   in "/stuff/k/git/kernel/Documentation/netlink/specs/ovs_datapath.yaml", line 14, column 9
> 

That error needs to be caught and handled in some more graceful way.

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.

Thanks,

jon