netdev - Re: [PATCH] Documentation: Document the Netlink spec

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <ZU0ktGJNbqTwjS3Q@gmail.com>
Date: Thu, 9 Nov 2023 10:28:04 -0800
From: Breno Leitao <leitao@...ian.org>
To: Donald Hunter <donald.hunter@...il.com>
Cc: corbet@....net, linux-doc@...r.kernel.org, netdev@...r.kernel.org,
	kuba@...nel.org, pabeni@...hat.com, edumazet@...gle.com
Subject: Re: [PATCH] Documentation: Document the Netlink spec

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