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

[Mauro Carvalho Chehab]

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.


Mauro Carvalho Chehab (6):
  get_abi.pl: fix parsing on ReST mode
  ABI: sysfs-driver-mlxreg-io: fix the what fields
  ABI: README: specify that files should be ReST compatible
  ABI: stable: make files ReST compatible
  docs: ABI: make it parse ABI/stable as ReST-compatible files
  docs: abi: create a 2-depth index for ABI

 Documentation/ABI/README                      | 10 +-
 Documentation/ABI/stable/firewire-cdev        |  4 +
 Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
 Documentation/ABI/stable/sysfs-bus-firewire   |  3 +
 Documentation/ABI/stable/sysfs-bus-nvmem      | 19 ++--
 Documentation/ABI/stable/sysfs-bus-usb        |  6 +-
 .../ABI/stable/sysfs-class-backlight          |  1 +
 .../ABI/stable/sysfs-class-infiniband         | 97 +++++++++++++------
 Documentation/ABI/stable/sysfs-class-rfkill   | 13 ++-
 Documentation/ABI/stable/sysfs-class-tpm      | 90 ++++++++---------
 Documentation/ABI/stable/sysfs-devices        |  5 +-
 Documentation/ABI/stable/sysfs-driver-ib_srp  |  1 +
 .../ABI/stable/sysfs-driver-mlxreg-io         | 45 ++++-----
 .../ABI/stable/sysfs-firmware-efi-vars        |  4 +
 .../ABI/stable/sysfs-firmware-opal-dump       |  5 +
 .../ABI/stable/sysfs-firmware-opal-elog       |  2 +
 Documentation/ABI/stable/sysfs-hypervisor-xen |  3 +
 Documentation/ABI/stable/vdso                 |  5 +-
 Documentation/admin-guide/abi-stable.rst      |  1 +
 Documentation/admin-guide/abi.rst             |  2 +-
 Documentation/sphinx/kernel_abi.py            |  9 +-
 scripts/get_abi.pl                            | 30 +++---
 22 files changed, 231 insertions(+), 146 deletions(-)

-- 
2.21.0