[00/14] Add support to generate ABI documentation at admin-guide

Message

Mauro Carvalho Chehab June 14, 2019, 2:04 a.m. UTC

Greg,

As promised, I'm resending the patch series with adds the Kernel ABI to
Documentation/admin-guide.

Those patches are basically the version 3 patchset I sent back in 2017,
rebased on the top of linux-next (next-20190613), and with some fixes
in order for it to work.

- The 4 initial patches to fix some ABI descriptions that are violating 
  the syntax described at Documentation/ABI/README;

- The next 6 patches are the ones originally written in 2017 with a
  script with parses the ABI files;

- The 11th patch is a new one: it relaxes a little bit the parser in 
  order to parse file headers that contains colons on it;

- The 12th patch adds the new script to the documentation build
  system, together with a new python Sphinx extension with calls it;

- The 13th patch fixes the python script when running with newer
  Sphinx versions (1.7 and upper);

- The final patch fixes an UTF-8 trouble. I noticed it only with Sphinx
  1.4, but it could affect other versions too. So, I ended by changing
  the UTF-8 encoding logit to work version-independent, just like
  what happens with kerneldoc.py extension.

Mauro Carvalho Chehab (14):
  ABI: fix some syntax issues at the ABI database
  ABI: sysfs-driver-hid: the "What" field doesn't parse fine
  ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry
  ABI: better identificate tables
  scripts: add an script to parse the ABI files
  scripts/get_abi.pl: parse files with text at beginning
  scripts/get_abi.pl: avoid use literal blocks when not needed
  scripts/get_abi.pl: split label naming from xref logic
  scripts/get_abi.pl: add support for searching for ABI symbols
  scripts/get_abi.pl: represent what in tables
  scripts/get_abi.pl: fix parse issues with some files
  doc-rst: add ABI documentation to the admin-guide book
  sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
  docs: sphinx/kernel_abi.py: fix UTF-8 support

 .../ABI/obsolete/sysfs-driver-hid-roccat-pyra |   2 +-
 Documentation/ABI/testing/pstore              |   2 +-
 .../sysfs-bus-event_source-devices-format     |   2 +-
 .../ABI/testing/sysfs-bus-i2c-devices-hm6352  |   6 +-
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |   4 +-
 .../testing/sysfs-bus-iio-proximity-as3935    |   4 +-
 .../ABI/testing/sysfs-bus-pci-devices-cciss   |  22 +-
 .../testing/sysfs-bus-usb-devices-usbsevseg   |  12 +-
 .../sysfs-class-backlight-driver-lm3533       |   6 +-
 Documentation/ABI/testing/sysfs-class-cxl     |   6 +-
 Documentation/ABI/testing/sysfs-class-devfreq |   2 +-
 .../ABI/testing/sysfs-class-led-driver-lm3533 |   8 +-
 .../ABI/testing/sysfs-class-leds-gt683r       |   4 +-
 .../ABI/testing/sysfs-class-powercap          |   2 +-
 Documentation/ABI/testing/sysfs-class-uwb_rc  |   6 -
 Documentation/ABI/testing/sysfs-driver-hid    |  12 +-
 .../ABI/testing/sysfs-driver-hid-roccat-kone  |   2 +-
 Documentation/ABI/testing/sysfs-kernel-fscaps |   2 +-
 .../ABI/testing/sysfs-kernel-vmcoreinfo       |   2 +-
 Documentation/admin-guide/abi-obsolete.rst    |  10 +
 Documentation/admin-guide/abi-removed.rst     |   4 +
 Documentation/admin-guide/abi-stable.rst      |  13 +
 Documentation/admin-guide/abi-testing.rst     |  19 +
 Documentation/admin-guide/abi.rst             |  11 +
 Documentation/admin-guide/index.rst           |   1 +
 Documentation/conf.py                         |   2 +-
 Documentation/sphinx/kernel_abi.py            | 172 +++++++
 scripts/get_abi.pl                            | 450 ++++++++++++++++++
 28 files changed, 731 insertions(+), 57 deletions(-)
 create mode 100644 Documentation/admin-guide/abi-obsolete.rst
 create mode 100644 Documentation/admin-guide/abi-removed.rst
 create mode 100644 Documentation/admin-guide/abi-stable.rst
 create mode 100644 Documentation/admin-guide/abi-testing.rst
 create mode 100644 Documentation/admin-guide/abi.rst
 create mode 100644 Documentation/sphinx/kernel_abi.py
 create mode 100755 scripts/get_abi.pl

Comments

Greg Kroah-Hartman June 14, 2019, 4:20 p.m. UTC | #1

On Thu, Jun 13, 2019 at 11:04:06PM -0300, Mauro Carvalho Chehab wrote:
> Greg,
> 
> As promised, I'm resending the patch series with adds the Kernel ABI to
> Documentation/admin-guide.
> 
> Those patches are basically the version 3 patchset I sent back in 2017,
> rebased on the top of linux-next (next-20190613), and with some fixes
> in order for it to work.
> 
> - The 4 initial patches to fix some ABI descriptions that are violating 
>   the syntax described at Documentation/ABI/README;

These 4 are now applied to my driver-core tree, thanks.

greg k-h