Re: [PATCH] docs: organize subsystems

[Bagas Sanjaya <bagasdotme@gmail.com>]

On Wed, May 31, 2023 at 01:17:15PM +0300, Costa Shulyupin wrote:
> as requested.
> 
> Add classes:
> * Core subsystems
> * Storage interfaces
> * Networking interfaces
> * Peripherals interfaces
> * Embedded interfaces
> * Other subsystems

This is v2, right? If so, please properly version your patch(es).

> 
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
> ---
>  Documentation/subsystem-apis.rst | 87 +++++++++++++++++++++++---------
>  1 file changed, 64 insertions(+), 23 deletions(-)
> 
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index 55c90d5383ef..20655f6092c2 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -10,6 +10,22 @@ is taken directly from the kernel source, with supplemental material added
>  as needed (or at least as we managed to add it — probably *not* all that is
>  needed).
>  
> +Core subsystems
> +---------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   core-api/index
> +   driver-api/index
> +   scheduler/index
> +   timers/index
> +   locking/index
> +   cpu-freq/index
> +   mm/index
> +   power/index
> +
> +
>  Human interfaces
>  ----------------
>  
> @@ -22,46 +38,71 @@ Human interfaces
>     gpu/index
>     fb/index
>  
> -**Fixme**: much more organizational work is needed here.
> +
> +Storage interfaces
> +------------------
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   driver-api/index
> -   core-api/index
> -   locking/index
> -   accounting/index
> +   filesystems/index
>     block/index
>     cdrom/index
> -   cpu-freq/index
> -   fpga/index
> -   i2c/index
> -   iio/index
> +   scsi/index
> +   target/index
> +
> +
> +Networking interfaces
> +---------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
>     isdn/index
>     infiniband/index
> -   leds/index
>     netlabel/index
>     networking/index
> -   pcmcia/index
> -   power/index
> -   target/index
> -   timers/index
> +   mhi/index
> +
> +
> +Peripherals interfaces
> +----------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   usb/index
> +   PCI/index
> +   hwmon/index
> +   leds/index
> +
> +
> +Embedded interfaces
> +-------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   fpga/index
> +   i2c/index
> +   iio/index
>     spi/index
>     w1/index
> +   peci/index
> +
> +Other subsystems
> +----------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   accounting/index
> +   pcmcia/index
>     watchdog/index
>     virt/index
> -   hwmon/index
>     accel/index
>     security/index
>     crypto/index
> -   filesystems/index
> -   mm/index
>     bpf/index
> -   usb/index
> -   PCI/index
> -   scsi/index
>     misc-devices/index
> -   scheduler/index
> -   mhi/index
> -   peci/index
>     wmi/index

There is more to be sorted, though (and mind patch description, because I
rewrite it):

---- >8 ----
From 81bcb6042497a829ec4e3880cb75fc5c7e7e4e2b Mon Sep 17 00:00:00 2001
From: Costa Shulyupin <costa.shul@redhat.com>
Date: Wed, 31 May 2023 13:17:15 +0300
Subject: [PATCH] Documentation: subsystem-apis: Categorize remaining
 subsystems

There is a FIXME that says to organize subsystems listed in
subsystem-apis.rst. Fulfill it by categorize remaining subsytems
by purpose/themes, while sorting entries in each category.

HID devices are already categorized in 3c591cc954d56e ("docs:
consolidate human interface subsystems").

Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
Link: https://lore.kernel.org/r/20230531101715.3256681-1-costa.shul@redhat.com
[Bagas: rewrite patch description to be clearer and categorize a few more subsystems]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/subsystem-apis.rst | 123 ++++++++++++++++++++++---------
 1 file changed, 88 insertions(+), 35 deletions(-)

diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
index 55c90d5383ef88..2c0b18a66e4e00 100644
--- a/Documentation/subsystem-apis.rst
+++ b/Documentation/subsystem-apis.rst
@@ -10,58 +10,111 @@ is taken directly from the kernel source, with supplemental material added
 as needed (or at least as we managed to add it — probably *not* all that is
 needed).
 
+Core subsystems
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   core-api/index
+   cpu-freq/index
+   driver-api/index
+   locking/index
+   mm/index
+   power/index
+   scheduler/index
+   timers/index
+   wmi/index
+
 Human interfaces
 ----------------
 
 .. toctree::
    :maxdepth: 1
 
-   input/index
-   hid/index
-   sound/index
-   gpu/index
    fb/index
+   gpu/index
+   hid/index
+   input/index
+   sound/index
 
-**Fixme**: much more organizational work is needed here.
+Storage
+-------
 
 .. toctree::
    :maxdepth: 1
 
-   driver-api/index
-   core-api/index
-   locking/index
-   accounting/index
    block/index
    cdrom/index
-   cpu-freq/index
+   filesystems/index
+   pcmcia/index
+   scsi/index
+   target/index
+
+
+Networking
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   bpf/index
+   infiniband/index
+   isdn/index
+   mhi/index
+   netlabel/index
+   networking/index
+
+
+Peripherals and devices
+-----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   PCI/index
+   hwmon/index
+   leds/index
+   misc-devices/index
+   usb/index
+
+
+Embedded systems
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
    fpga/index
    i2c/index
    iio/index
-   isdn/index
-   infiniband/index
-   leds/index
-   netlabel/index
-   networking/index
-   pcmcia/index
-   power/index
-   target/index
-   timers/index
+   peci/index
    spi/index
    w1/index
-   watchdog/index
-   virt/index
-   hwmon/index
-   accel/index
-   security/index
+
+Integrity
+---------
+
+.. toctree::
+   :maxdepth: 1
+
    crypto/index
-   filesystems/index
-   mm/index
-   bpf/index
-   usb/index
-   PCI/index
-   scsi/index
-   misc-devices/index
-   scheduler/index
-   mhi/index
-   peci/index
-   wmi/index
+   security/index
+
+Virtualization
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   virt/index
+
+Miscellaneous
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   accel/index
+   accounting/index
+   watchdog/index
-- 
An old man doll... just what I always wanted! - Clara

Thanks.

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