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: <875y2cxa6n.fsf@meer.lwn.net>
Date: Wed, 08 Nov 2023 13:27:28 -0700
From: Jonathan Corbet <corbet@....net>
To: Breno Leitao <leitao@...ian.org>
Cc: 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

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.

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