Jonathan Corbet <corbet@xxxxxxx> writes: > Breno Leitao <leitao@xxxxxxxxxx> 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@xxxxxxxxxxxx/ 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@xxxxxxxxx/ 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
