Re: [PATCH] Documentation: Document the Netlink spec

[Donald Hunter <donald.hunter@gmail.com>]

Jonathan Corbet <corbet@lwn.net> writes:

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

+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/

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.

> Thanks,
>
> jon