Re: [PATCH v3] Documentation: Document each netlink family

[Jani Nikula]

On Tue, 30 Jan 2024, Jonathan Corbet <corbet@xxxxxxx> wrote:
> Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> writes:
>
>> On Tue, 21 Nov 2023, Breno Leitao <leitao@xxxxxxxxxx> wrote:
>>> 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@xxxxxxxxxx/
>
> 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