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. Thanks, jon
