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 for Android: free password hash cracker in your pocket

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

Message-ID: <m2h6lvmasi.fsf@gmail.com>
Date: Thu, 09 Nov 2023 11:22:05 +0000
From: Donald Hunter <donald.hunter@...il.com>
To: Jonathan Corbet <corbet@....net>
Cc: Breno Leitao <leitao@...ian.org>,  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

Jonathan Corbet <corbet@....net> writes:

> 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.

+1 to this. The .rst generation can then be easily tested independently
of the doc build and the stub files could be avoided.

Just a note that last year you offered the opposite guidance:

https://lore.kernel.org/linux-doc/87tu4zsfse.fsf@meer.lwn.net/

If the preference now is for standalone scripts invoked by the Makefile
then this previous patch might be useful:

https://lore.kernel.org/linux-doc/20220922115257.99815-2-donald.hunter@gmail.com/

It would be good to document the preferred approach to this kind of doc
extension and I'd be happy to contribute an 'Extensions' section for
contributing.rst in the doc-guide.

> Thanks,
>
> jon