Re: [PATCH] Documentation: Add category of subsystem-apis

[Manuel Ebner <manuelebnerli@mailbox.org>]

Hi Randy,

On Thu, 2026-11-05 at 14:01 -0800, Randy Dunlap wrote:
> On 11/5/26 10:15 AM, Manuel Ebner wrote:
> > Add Bus and Communication category to reduce number of items in
> > 'Other subsystems'.
> > 
> > Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> driver-api/index.html
> This LGTM but at first I was wondering why I2C is listed here but I3C
> is not.  I3C is listed under driver-api/index.html. So are some other
> buses.

I think the actual reason is: There is Documentation/i2c/
but no Documentation/i3c/ . subsystem-apis.rst links to Documentation/<name>/index.rst ,
core-api/index.rst links to Documentation/core-api/<name>.rst .

however there is driver-api/i2c.rst and driver-api/i3c/index.rst.
Thats why Documentation/driver-api/index.rst has this:
> Bus-level documentation
>     ...
>     I3C subsystem
>     ...
> Subsystem-specific APIs
>     ...
>     I2C and SMBus Subsystem

The structure is weird.

driver-api/index's justification is clearly stated, subsystem-apis's isn't.
What is it?


> That is a little confusing to me. ISTM that we need so *not* have
> 2 places listing bus documentation...

I'm not sure about that. If the files serve to different people/roles both
should be kept, adapted and refined.

> Anyway, this is a good start on that. It could be merged as is.
> 
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks
 Manuel

> 
> > ---
> >  Documentation/subsystem-apis.rst | 21 ++++++++++++++-------
> >  1 file changed, 14 insertions(+), 7 deletions(-)
> > 
> > diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> > index b1ad48bb40..4e886897d3 100644
> > --- a/Documentation/subsystem-apis.rst
> > +++ b/Documentation/subsystem-apis.rst
> > @@ -24,6 +24,20 @@ Core subsystems
> >     timers/index
> >     locking/index
> >  
> > +Bus and Communication interfaces
> > +--------------------------------
> > +
> > +.. toctree::
> > +   :maxdepth: 1
> > +
> > +   i2c/index
> > +   pcmcia/index
> > +   spi/index
> > +   w1/index
> > +   usb/index
> > +   PCI/index
> > +   peci/index
> > +
> >  Human interfaces
> >  ----------------
> >  
> > @@ -72,11 +86,7 @@ Other subsystems
> >     cpu-freq/index
> >     edac/index
> >     fpga/index
> > -   i2c/index
> >     iio/index
> > -   pcmcia/index
> > -   spi/index
> > -   w1/index
> >     watchdog/index
> >     virt/index
> >     hwmon/index
> > @@ -84,9 +94,6 @@ Other subsystems
> >     security/index
> >     crypto/index
> >     bpf/index
> > -   usb/index
> > -   PCI/index
> >     misc-devices/index
> > -   peci/index
> >     wmi/index
> >     tee/index