On Tue, 30 Jan 2024, Jonathan Corbet [off-list ref] wrote:

Jani Nikula [off-list ref] writes:

quoted

On Tue, 21 Nov 2023, Breno Leitao [off-list ref] wrote:

quoted

This is a simple script that parses the Netlink YAML spec files
(Documentation/netlink/specs/), and generates RST files to be rendered
in the Network -> Netlink Specification documentation page.

First of all, my boilerplate complaint: All extra processing for Sphinx
should really be done using Sphinx extensions instead of adding Makefile
hacks. I don't think it's sustainable to keep adding this stuff. We
chose Sphinx because it is extensible, and to avoid the Rube Goldberg
machine that the previous documentation build system was.

So I feel like we've (me included) have kind of sent Breno around in
circles on this one.  This *was* implemented as an extension once:

  https://lore.kernel.org/netdev/20231103135622.250314-1-leitao@debian.org/ (local)

At that time it seemed too complex, and I thought that an external
script would lead to a simpler implementation overall.  Perhaps I was
wrong.

I worry that a proliferation of extensions adds its own sort of
complexity and hazards - look at the things Vegard has fixed recently,
for example.

If we're talking about the same things, I think one of the main problems
there was shelling out to an external script while it could all have
been trivially implemented directly in the extension. ;)

Relatively few people can work in that environment, and
extensions can make our version-support troubles worse.  So I'm not
fully sold on the idea that everything should be an extension,
especially if it can be expressed as a simple dependency and build step
in the makefile.

I think we're just going to have to agree to disagree here. And,
ultimately, it's your call as the documentation maintainer.

I'm sure some individual things are simple to put in the makefiles, but
I believe overall the entire thing would be simpler if we avoided that.

Some of the uglier makefile stuff we have is a different story...

Anyway, I apologize for my role in making this particular addition
harder than it needed to be.  Perhaps, for the future, we should put
together and agree on a document (of all things) on how we think this
sort of functionality should be added.

Perhaps. The problem at hand, though, is that after 'make
O=/path/to/build htmldocs' I have this cruft in my source tree:

$ git ls-files -oi --exclude-per-directory=.gitignore
Documentation/networking/netlink_spec/devlink.rst
Documentation/networking/netlink_spec/dpll.rst
Documentation/networking/netlink_spec/ethtool.rst
Documentation/networking/netlink_spec/fou.rst
Documentation/networking/netlink_spec/handshake.rst
Documentation/networking/netlink_spec/index.rst
Documentation/networking/netlink_spec/mptcp_pm.rst
Documentation/networking/netlink_spec/netdev.rst
Documentation/networking/netlink_spec/nfsd.rst
Documentation/networking/netlink_spec/ovs_datapath.rst
Documentation/networking/netlink_spec/ovs_flow.rst
Documentation/networking/netlink_spec/ovs_vport.rst
Documentation/networking/netlink_spec/rt_addr.rst
Documentation/networking/netlink_spec/rt_link.rst
Documentation/networking/netlink_spec/rt_route.rst
Documentation/networking/netlink_spec/tc.rst

I'm not even sure what the best way to fix that would be. (Apart from
turning it into an extension, of course. ;)


BR,
Jani.


-- 
Jani Nikula, Intel