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: <87r0kzuiax.fsf@meer.lwn.net>
Date: Thu, 09 Nov 2023 07:12:38 -0700
From: Jonathan Corbet <corbet@....net>
To: Donald Hunter <donald.hunter@...il.com>
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

Donald Hunter <donald.hunter@...il.com> writes:

> Jonathan Corbet <corbet@....net> writes:
>> 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/

Heh ... I totally forgot about that whole discussion ...

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

I think it will vary depending on what we're trying to do, and I think
we're still working it out - part of why I expressed some uncertainty
this time around.

For something like the kernel-doc or automarkup, where we are modifying
existing documents, an extension is the only way to go.  In this case,
where we are creating new RST files from whole cloth, it's not so clear
to me.  My feeling (this week at least ;) is that doing it as an
extension makes things more complicated without a lot of benefit.

FWIW, if something like this is done as a makefile change, I'd do it a
bit differently than your linked patch above.  Rather than replicate the
command through the file, I'd just add a new target:

  netlink_specs:
  	.../scripts/gen-netlink-rst

  htmldocs: netlink_specs
  	existing stuff here

But that's a detail.

Thanks,

jon