netdev - Re: [PATCH net-next] net: Reorganize networking documentation toctree

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] [day] [month] [year] [list]

Message-ID: <b585fa87-b804-4f7c-844d-86645c61b2ca@infradead.org>
Date: Wed, 29 Oct 2025 18:26:02 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Bagas Sanjaya <bagasdotme@...il.com>,
 Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
 Linux Documentation <linux-doc@...r.kernel.org>,
 Linux Networking <netdev@...r.kernel.org>, Linux BPF <bpf@...r.kernel.org>
Cc: "David S. Miller" <davem@...emloft.net>,
 Eric Dumazet <edumazet@...gle.com>, Jakub Kicinski <kuba@...nel.org>,
 Paolo Abeni <pabeni@...hat.com>, Simon Horman <horms@...nel.org>,
 Jonathan Corbet <corbet@....net>, Alexei Starovoitov <ast@...nel.org>,
 Daniel Borkmann <daniel@...earbox.net>,
 Jesper Dangaard Brouer <hawk@...nel.org>,
 John Fastabend <john.fastabend@...il.com>,
 Stanislav Fomichev <sdf@...ichev.me>
Subject: Re: [PATCH net-next] net: Reorganize networking documentation toctree

On 10/28/25 4:39 AM, Bagas Sanjaya wrote:
> Current netdev docs has one large, unorganized toctree that makes
> finding relevant docs harder like a needle in a haystack. Split the
> toctree into four categories: networking core; protocols; devices; and
> assorted miscellaneous.
> 
> While at it, also sort the toctree entries and reduce toctree depth.

Hm, I was going to ask how they are sorted, but I see that it's by
file name -- chapter headings aren't sorted. E.g., under Protocols,

ARCnet
AX.25
Bare UDP Tunnelling Module Documentation
CAIF
SocketCAN - Controller Area Network
The UCAN Protocol
DCTCP (DataCenter TCP)
The Linux kernel GTP tunneling module
Identifier Locator Addressing (ILA)
IPsec
IPv6

These are sorted by file name. I'm not complaining, just
making an observation.

Another observation: I find the heading
  Softnet Driver Issues
confusing, since I can't find anything in
Documentation/networking/ that tells me what Softnet means.
(and yes, I know, you didn't add this, just moved it)

I like the organization. Someone might quibble over a few
entries and which section heading they should be in, but
that can be changed any time. (mostly items under
Miscellaneous; e.g. RDS is a protocol)

The size of the new index page is nice (about 3 screens on my
laptop). But I miss seeing the next level of headings
(:maxdepth: 2 instead of 1). And I don't see any way to find
that. It would be nice if I could click on a hamburger menu
somewhere to see finer detailed TOC/index. Or if the
sidebar TOC could be expanded by clicking on a heading.

And I don't think that the line "Contents:" at the top is doing
any good.

So I tried this patch with :maxdepth: 2. There is still too much
TOC info there IMO, so using :maxdepth: 1 is good.
I just wish there was a way to see individual (page) TOCs on demand.

Reviewed-by: Randy Dunlap <rdunlap@...radead.org>
Tested-by: Randy Dunlap <rdunlap@...radead.org>

Thanks.

> Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
> ---
>  Documentation/networking/index.rst | 241 ++++++++++++++++-------------
>  1 file changed, 136 insertions(+), 105 deletions(-)
> 
> diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
> index c775cababc8c17..ca86e544c5c8e2 100644
> --- a/Documentation/networking/index.rst
> +++ b/Documentation/networking/index.rst
> @@ -5,138 +5,169 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics.

-- 
~Randy