On Wed, Nov 08, 2023 at 02:03:34PM +0000, Donald Hunter wrote: > 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. > > This is great! Looks like I need to fill in some missing docs in the > specs I have contributed. > > I wonder if the generated .rst content can be adjusted to improve the > resulting HTML. > > There are a couple of places where paragraph text is indented and I > don't think it needs to be, e.g. the 'Summary' doc. > > A lot of the .rst content seems to be over-indented which causes > blockquote tags to be generated in the HTML. That combined with a > mixture of bullets and definition lists at the same indentation level > seems to produce HTML with inconsistent indentation. > > I quickly hacked the diff below to see if it would improve the HTML > rendering. I think the HTML has fewer odd constructs and the indentation > seems better to my eye. My main aim was to ensure that for a given > section, each indentation level uses the same construct, whether it be a > definition list or a bullet list. Thanks for the diff. That makes total sense and I will integrate it in the updated version. > It would be great to generate links from e.g. an attribute-set to its > definition. > > Did you intentionally leave out the protocol values? Yes. This could be done in a follow up patch if necessary. > > It looks like parse_entries will need to be extended to include the type > information for struct members, similar to how attribute sets are shown. > I'd be happy to look at this as a follow up patch, unless you get there > first. Awesome. That would be appreciate.
