Re: [PATCH net v2 1/2] docs: networking: convert DIM to RST

[Jakub Kicinski <kuba@kernel.org>]

On Thu, 9 Apr 2020 22:46:55 +0000 Saeed Mahameed wrote:
> On Thu, 2020-04-09 at 14:21 -0700, Jakub Kicinski wrote:
> > Convert the Dynamic Interrupt Moderation doc to RST and
> > use the RST features like syntax highlight, function and
> > structure documentation, enumerations, table of contents.
> > 
> > Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> > ---
> > v2:
> >  - remove the functions/type definition markup
> >  - change the contents definition (the :local: seem to
> >    not work too well with kdoc)
> > ---
> >  Documentation/networking/index.rst            |  1 +
> >  .../networking/{net_dim.txt => net_dim.rst}   | 90 +++++++++------
> > ----
> >  MAINTAINERS                                   |  1 +
> >  3 files changed, 45 insertions(+), 47 deletions(-)
> >  rename Documentation/networking/{net_dim.txt => net_dim.rst} (79%)
> > 
> > diff --git a/Documentation/networking/index.rst
> > b/Documentation/networking/index.rst
> > index 50133d9761c9..6538ede29661 100644
> > --- a/Documentation/networking/index.rst
> > +++ b/Documentation/networking/index.rst
> > @@ -22,6 +22,7 @@ Linux Networking Documentation
> >     z8530book
> >     msg_zerocopy
> >     failover
> > +   net_dim  
> 
> net_dim is a performance feature, i would move further down the list
> where the perf features such as scaling and offloads are .. 

I mean.. so is msg_zerocopy just above ;-)  I spotted slight
alphabetical ordering there, which may have not been intentional,
that's why I put it here. Marking with # things out of order, but 
based on just the first letter:

#  netdev-FAQ
   af_xdp
   bareudp
   batman-adv
   can
   can_ucan_protocol
   device_drivers/index
   dsa/index
   devlink/index
   ethtool-netlink
   ieee802154
   j1939
   kapi
#  z8530book
   msg_zerocopy
#  failover
   net_dim
   net_failover
   phy
   sfp-phylink
#  alias
#  bridge
   snmp_counter
#  checksum-offloads
   segmentation-offloads
   scaling
   tls
   tls-offload
#  nfc
   6lowpan

My feeling is that we should start considering splitting kernel-only
docs and admin-only docs for networking, which I believe is the
direction Jon and folks want Documentation/ to go. But I wasn't brave
enough to be the first one. Then we can impose some more structure,
like putting all "performance" docs in one subdir..?

WDYT?