Re: [PATCH] Documentation: Document the Netlink spec

[Breno Leitao <leitao@debian.org>]

On Wed, Nov 08, 2023 at 02:03:34PM +0000, Donald Hunter wrote:
> 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.
> 
> 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.