[lkml]   [2017]   [Apr]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Subject[PATCH v2 00/11] Documentation: Add ABI to the admin guide

That's the third attempt to add support for the Kernel ABI
at the Documentation's admin guide.

The first approach was based on a generic extension that
calls a random script. This one is based on a new Sphinx
extension with adds a symbol specific for parsing ABI

It adds a new script (scripts/ with can either
search for ABI symbols that match a regular expression or
outputs the entire documentation found inside a directory
as a ReST book.

Adding the ABI description to the Linux documentation is
as easy as adding a tab like:

.. kernel-abi:: $srctree/Documentation/ABI/obsolete

On version 3, I improved the script to better parse the
ABI descriptions. On this version, it will identify if the
description can be handled as a normal text. If so, it will
escape characters that has special meaning on Sphinx.
If it detects that the description syntax is too complex,
it outputs inside a literal block.

Also on version 3, I opted to use 4 separate sections, one
for each type of symbol. It also add an entry with the name
of each ABI file, with has cross-references to the symbols
defined on each file.

The parser was also improved to handle any content at the
files that are before the ABI tags.

The first 3 patches on this series fix some syntax errors
on some ABI description.

The next one makes sure that, when a table is present on
the description, the preceding line will end with a colon
(with is one of the ways the script uses to identify
complex layouts).


IMHO, we should add another ABI tag to allow using an
enriched text description, e. g. instead of:

Description: foo

One could use, instead, something like:

ReST-description: foo

On such case, the script wouldn't need to escape the
description contents, as they can be just sent directly to
the ABI ReST output.

Markus Heiser (1):
doc-rst: customize RTD theme; literal-block

Mauro Carvalho Chehab (10):
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/ parse files with text at beginning
scripts/ avoid use literal blocks when not needed
scripts/ split label naming from xref logic
scripts/ add support for searching for ABI symbols
doc-rst: add ABI documentation to the admin-guide book

.../ABI/obsolete/sysfs-driver-hid-roccat-pyra | 2 +-
Documentation/ABI/testing/pstore | 2 +-
.../testing/sysfs-bus-event_source-devices-format | 2 +-
.../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 +-
.../ABI/testing/sysfs-bus-iio-distance-srf08 | 4 +-
.../ABI/testing/sysfs-bus-iio-proximity-as3935 | 4 +-
.../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +-
.../ABI/testing/sysfs-bus-usb-devices-usbsevseg | 12 +-
.../testing/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 +-
Documentation/ABI/testing/sysfs-class-leds-gt683r | 4 +-
Documentation/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 +-
Documentation/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/ | 3 +-
Documentation/sphinx-static/theme_overrides.css | 7 +
Documentation/sphinx/ | 155 ++++++++
scripts/ | 419 +++++++++++++++++++++
29 files changed, 691 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/
create mode 100755 scripts/


 \ /
  Last update: 2017-04-13 12:12    [W:0.097 / U:3.212 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site