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

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

[Bagas Sanjaya]

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.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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.
 
 Contents:
 
+Networking core
+---------------
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    af_xdp
-   bareudp
-   batman-adv
-   can
-   can_ucan_protocol
-   device_drivers/index
-   diagnostic/index
-   dsa/index
-   devlink/index
-   caif/index
-   ethtool-netlink
-   ieee802154
-   iso15765-2
-   j1939
-   kapi
-   msg_zerocopy
-   failover
-   net_dim
-   net_failover
-   page_pool
-   phy
-   sfp-phylink
-   alias
-   bridge
-   snmp_counter
    checksum-offloads
-   segmentation-offloads
-   scaling
-   tls
-   tls-offload
-   tls-handshake
-   nfc
-   6lowpan
-   6pack
-   arcnet-hardware
-   arcnet
-   atm
-   ax25
-   bonding
-   cdc_mbim
-   dctcp
-   devmem
-   dns_resolver
+   diagnostic/index
    driver
-   eql
-   fib_trie
-   filter
-   generic-hdlc
-   generic_netlink
-   ../netlink/specs/index
-   gen_stats
-   gtp
-   ila
-   ioam6-sysctl
-   iou-zcrx
-   ip_dynaddr
-   ipsec
-   ip-sysctl
-   ipv6
-   ipvlan
-   ipvs-sysctl
-   kcm
-   l2tp
-   lapb-module
+   kapi
    mac80211-injection
-   mctp
-   mpls-sysctl
-   mptcp
-   mptcp-sysctl
-   multiqueue
-   multi-pf-netdev
+   msg_zerocopy
    napi
    net_cachelines/index
-   netconsole
    netdev-features
-   netdevices
-   netfilter-sysctl
    netif-msg
-   netmem
-   nexthop-group-resilient
-   nf_conntrack-sysctl
-   nf_flowtable
-   oa-tc6-framework
-   openvswitch
-   operstates
    packet_mmap
-   phonet
+   page_pool
+   phy
    phy-link-topology
-   pktgen
+   scaling
+   segmentation-offloads
+   skbuff
+   strparser
+   timestamping
+   xdp-rx-metadata
+   xsk-tx-metadata
+
+Protocols
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   6pack
+   arcnet
+   ax25
+   bareudp
+   caif/index
+   can
+   can_ucan_protocol
+   dctcp
+   gtp
+   ila
+   ipsec
+   ipv6
+   iso15765-2
+   j1939
+   l2tp
+   mctp
+   mptcp
+   oa-tc6-framework
+   phonet
+   psp
+   rxrpc
+   sctp
+   tcp-thin
+   tcp_ao
+   tipc
+   tls
+   tls-handshake
+   tls-offload
+   udplite
+   vxlan
+   x25
+
+Networking devices
+------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   6lowpan
+   arcnet-hardware
+   bonding
+   bridge
+   cdc_mbim
+   device_drivers/index
+   devlink/index
+   devmem
+   dsa/index
+   eql
+   ipvlan
+   multi-pf-netdev
+   multiqueue
+   netconsole
+   netdevices
+   netmem
+   operstates
    plip
    ppp_generic
+   representors
+   sriov
+   statistics
+   switchdev
+   team
+   tuntap
+   vrf
+   x25-iface
+
+Packet filtering
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   filter
+   netfilter-sysctl
+   nf_conntrack-sysctl
+   nf_flowtable
+   tc-actions-env-rules
+   tc-queue-filters
+   tproxy
+
+Miscellaneous
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   ../netlink/specs/index
+   alias
+   atm
+   batman-adv
+   dns_resolver
+   ethtool-netlink
+   failover
+   fib_trie
+   gen_stats
+   generic-hdlc
+   generic_netlink
+   ieee802154
+   ioam6-sysctl
+   iou-zcrx
+   ip-sysctl
+   ip_dynaddr
+   ipvs-sysctl
+   kcm
+   lapb-module
+   mpls-sysctl
+   mptcp-sysctl
+   net_dim
+   net_failover
+   nexthop-group-resilient
+   nfc
+   openvswitch
+   pktgen
    proc_net_tcp
    pse-pd/index
-   psp
    radiotap-headers
    rds
    regulatory
-   representors
-   rxrpc
-   sctp
    secid
    seg6-sysctl
-   skbuff
+   sfp-phylink
    smc-sysctl
-   sriov
-   statistics
-   strparser
-   switchdev
+   snmp_counter
    sysfs-tagging
-   tc-actions-env-rules
-   tc-queue-filters
-   tcp_ao
-   tcp-thin
-   team
-   timestamping
-   tipc
-   tproxy
-   tuntap
-   udplite
-   vrf
-   vxlan
-   x25
-   x25-iface
    xfrm_device
    xfrm_proc
    xfrm_sync
    xfrm_sysctl
-   xdp-rx-metadata
-   xsk-tx-metadata
 
 .. only::  subproject and html
 

base-commit: 5f30bc470672f7b38a60d6641d519f308723085c
-- 
An old man doll... just what I always wanted! - Clara

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

[Randy Dunlap]

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@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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

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

[Jakub Kicinski]

On Tue, 28 Oct 2025 18:39:24 +0700 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.

Looking at the outcome -- I'm not sure we're achieving sufficient
categorization here. It's a hard problem to group these things.
What ends up under Networking devices and Miscellaneous seems
pretty random. Bunch of the entries under there should be in protocols
or core. And at the end of the day if we don't have a very intuitive
categorization the reader has to search anyway. So no point..
-- 
pw-bot: cr

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 983 bytes --]

On Thu, Oct 30, 2025 at 05:50:18PM -0700, Jakub Kicinski wrote:
> On Tue, 28 Oct 2025 18:39:24 +0700 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.
> 
> Looking at the outcome -- I'm not sure we're achieving sufficient
> categorization here. It's a hard problem to group these things.
> What ends up under Networking devices and Miscellaneous seems
> pretty random. Bunch of the entries under there should be in protocols
> or core. And at the end of the day if we don't have a very intuitive
> categorization the reader has to search anyway. So no point..

Do you have any categorization suggestions then?

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Jakub Kicinski]

On Fri, 31 Oct 2025 08:11:44 +0700 Bagas Sanjaya wrote:
> On Thu, Oct 30, 2025 at 05:50:18PM -0700, Jakub Kicinski wrote:
> > On Tue, 28 Oct 2025 18:39:24 +0700 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.  
> > 
> > Looking at the outcome -- I'm not sure we're achieving sufficient
> > categorization here. It's a hard problem to group these things.
> > What ends up under Networking devices and Miscellaneous seems
> > pretty random. Bunch of the entries under there should be in protocols
> > or core. And at the end of the day if we don't have a very intuitive
> > categorization the reader has to search anyway. So no point..  
> 
> Do you have any categorization suggestions then?

No.

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1207 bytes --]

On Thu, Oct 30, 2025 at 06:22:51PM -0700, Jakub Kicinski wrote:
> On Fri, 31 Oct 2025 08:11:44 +0700 Bagas Sanjaya wrote:
> > On Thu, Oct 30, 2025 at 05:50:18PM -0700, Jakub Kicinski wrote:
> > > On Tue, 28 Oct 2025 18:39:24 +0700 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.  
> > > 
> > > Looking at the outcome -- I'm not sure we're achieving sufficient
> > > categorization here. It's a hard problem to group these things.
> > > What ends up under Networking devices and Miscellaneous seems
> > > pretty random. Bunch of the entries under there should be in protocols
> > > or core. And at the end of the day if we don't have a very intuitive
> > > categorization the reader has to search anyway. So no point..  
> > 
> > Do you have any categorization suggestions then?
> 
> No.

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]