Donald Hunter <donald.hunter@xxxxxxxxx> writes: > Jonathan Corbet <corbet@xxxxxxx> 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@xxxxxxxxxxxx/ 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@xxxxxxxxx/ > > 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
