Re: [PATCH RFC 0/6] Produce ABI guide without escaping ReST source files

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Fri, 21 Jun 2019 09:32:00 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:

> Hi Greg,
> 
> As you proposed to give it a try on removing the escape code from the
> script which parses the ReST file, I changed a few things there,
> adding the capability of selectively enabling to output an ABI sub-dir
> without escaping things that would crash Sphinx.
> 
> PS.: As for now this is just a RFC, I'm not getting the ABI file
> maintainers, copying just LKML, linux-doc ML, plus you and Jon.
> 
> I also manually fixed the contents of ABI/stable, in order for it to
> pass without causing troubles.
> 
> I added all patches from ABI and features at this branch:
> 
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
> 
> The html output is at https://www.infradead.org/~mchehab/rst_features/,
> and you can see the resulting ABI guide on:
> 
> 	https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> 
> No Sphinx crashes/warnings happen when building it.
> 
> That's my personal notes about such work:
> 
> 1) Documentation/ABI/stable/sysfs-class-infiniband
> 
> It had some title captions inside it, like:
> 
> 	Errors info:
>                 -----------
> 
> For one of the "What:"
> 
> Sphinx is really pick with title markups. As the entire Documentation/stable is
> parsed as if it were a single document, there should be a coherency on what
> character is used to markup a level-one title. I mean, if one document uses:
> 
> foo
> ----
> 
> For the first level, all other documents should use "---...-" as well.
> 
> The alternative would be to have one entry for every single file at
> Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
> harder to maintain.
> 
> So, the best seems to let clear at ABI/README about how titles/subtitles
> should be used inside files, if any.
> 
> 2) Some documents there use a "Values:" tag, with is not defined as a
> valid one at ABI/README. The script handles it as part of the description,
> so no harm done;
> 
> 3) Among the 47 files under ABI/stable, 14 of them names the file
> contents, using a valid ReST markup for the document title. That is shown
> at the index at:
> 
> 	https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> 
> 
> - ABI stable symbols
> 
>   -  sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
>   -  sysfs interface for Intel IB driver qib
>   -  sysfs interface for Intel(R) X722 iWARP i40iw driver
>   -  sysfs interface for QLogic qedr NIC Driver
>   -  sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
>   -  sysfs interface for Cisco VIC (usNIC) Verbs Driver
>   -  sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
>   -  sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
>   -  sysfs interface for Intel Omni-Path driver (HFI1)
>   -  sysfs interface for VMware Paravirtual RDMA driver
>   -  sysfs interface for Mellanox Connect-IB HCA driver mlx5
>   -  sysfs interface for Emulex RoCE HCA Driver
>   -  sysfs interface for Broadcom NetXtreme-E RoCE driver
>   -  sysfs interface for Mellanox IB HCA low-level driver (mthca)
> 
> I liked that, but ideally all ABI files should either use it or not.
> 
> 4) I was expecting to have troubles with asterisk characters inside the
> ABI files. That was not the case: I had to escape just one occurrence on
> a single file of the 47 ones inside ABI/stable. 
> 
> -
> 
> My conclusion from this experiment is that it is worth cleaning the ABI
> files for them to be parsed without needing to escape non-ReST compliant
> parts of the ABI file.
> 
> Perhaps we could keep rst-compliant the stable, obsolete and removed
> directories only, and gradually moving stuff from ABI/testing to ABI/stable,
> while fixing them to be rst-compliant.

Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and 
abi-removed.rst produced just two warnings:

get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.

I'll fix those too at my repository.

I suspect, however, that Documentation/ABI/testing with its 353 files will
require a lot more care.

Thanks,
Mauro

diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
index cda9168445a5..d095867899c5 100644
--- a/Documentation/admin-guide/abi-obsolete.rst
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -8,3 +8,4 @@ The description of the interface will document the reason why it is
 obsolete and when it can be expected to be removed.
 
 .. kernel-abi:: $srctree/Documentation/ABI/obsolete
+   :rst:
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
index 497978fc9632..f7e9e43023c1 100644
--- a/Documentation/admin-guide/abi-removed.rst
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -2,3 +2,4 @@ ABI removed symbols
 ===================
 
 .. kernel-abi:: $srctree/Documentation/ABI/removed
+   :rst: