Skip to content

RFC Produce ABI guide without escaping ReST source files

Mauro Carvalho Chehab linux-doc lkml 2 versions – New

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 RFC Latest8 patches 0 repliesNew
  2. v1 RFC6 patches 3 repliesSuperseded

Patches in v2 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/8docs: ABI: README: specify that files should be ReST compatibleDocumentation/ABI/README+9 -10 replies
2/8docs: ABI: stable: make files ReST compatibleDocumentation/ABI/stable/firewire-cdev Documentation/ABI/stable/sysfs-acpi-pmprofile Documentation/ABI/stable/sysfs-bus-firewire +13 more+180 -1000 replies
3/8docs: ABI: testing: make the files compatible with ReST outputDocumentation/ABI/testing/configfs-spear-pcie-gadget Documentation/ABI/testing/configfs-usb-gadget Documentation/ABI/testing/configfs-usb-gadget-hid +69 more+1226 -7980 replies
4/8docs: ABI: make it parse ABI/stable as ReST-compatible filesDocumentation/admin-guide/abi-stable.rst Documentation/sphinx/kernel_abi.py+7 -20 replies
5/8docs: ABI: create a 2-depth index for ABIDocumentation/admin-guide/abi.rst+1 -10 replies
6/8docs: ABI: don't escape ReST-incompatible chars from obsolete and removedDocumentation/ABI/obsolete/sysfs-gpio Documentation/admin-guide/abi-obsolete.rst Documentation/admin-guide/abi-removed.rst+4 -00 replies
7/8docs: abi-testing.rst: enable --rst-sources when building docsDocumentation/admin-guide/abi-testing.rst+1 -00 replies
8/8docs: Kconfig/Makefile: add a check for broken ABI filesDocumentation/Kconfig Documentation/Makefile lib/Kconfig.debug +1 more+29 -30 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.

Read the v2 thread

Cover letter [RFC v2 0/8]Produce ABI guide without escaping ReST source files

Hi Greg,

It turns out that fixing ABI/testing for it to be parsed transparently was easy :-)

This series goes on top of the series I pasted early today:

Subject: [PATCH 00/12] Add the ABI documentation to the admin guide

It basically change the ABI parser to not try to escape ReST code.

With that, the descriptions inside the ABI files should now be compatible with ReST output.

Patch 1 states that at ABI/README;

Patch 2 and 3 fix troubles at stable and testing ABI files. No changes at the content of the ABI themselves. Most of the changes there are due to some examples, tables and some parameter descriptions with weird formats.

Patch 4 enables the "clear mode" for stable;

Patch 5 is just a helper patch: it adds a second level to the ABI index, in order to allow seeing what sections the parsed files will produce;

patch 6 enables "clear mode" to obsolete and removed;

patch 7 enables "clear mode" to testing

-

Patch 8 is here just for us not to forget it - it causes any COMPILE_TEST build to validate if the ABI files are following the syntax described at ABI/README. It won't try to build it with Sphinx, though. As this is quick (~100ms on my desktop), I think it is worth to have it.

Mauro Carvalho Chehab (8):
docs: ABI: README: specify that files should be ReST compatible
docs: ABI: stable: make files ReST compatible
docs: ABI: testing: make the files compatible with ReST output
docs: ABI: make it parse ABI/stable as ReST-compatible files
docs: ABI: create a 2-depth index for ABI
docs: ABI: don't escape ReST-incompatible chars from obsolete and
removed
docs: abi-testing.rst: enable --rst-sources when building docs
docs: Kconfig/Makefile: add a check for broken ABI files

 Documentation/ABI/README                      |  10 +-
 Documentation/ABI/obsolete/sysfs-gpio         |   2 +
 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-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 +-
 .../ABI/testing/configfs-spear-pcie-gadget    |  36 +--
 Documentation/ABI/testing/configfs-usb-gadget |  77 +++---
 .../ABI/testing/configfs-usb-gadget-hid       |  10 +-
 .../ABI/testing/configfs-usb-gadget-rndis     |  16 +-
 .../ABI/testing/configfs-usb-gadget-uac1      |  18 +-
 .../ABI/testing/configfs-usb-gadget-uvc       | 220 +++++++++-------
 Documentation/ABI/testing/debugfs-ec          |  11 +-
 Documentation/ABI/testing/debugfs-pktcdvd     |  11 +-
 Documentation/ABI/testing/dev-kmsg            |  27 +-
 Documentation/ABI/testing/evm                 |  17 +-
 Documentation/ABI/testing/ima_policy          | 132 +++++-----
 Documentation/ABI/testing/procfs-diskstats    |  40 +--
 Documentation/ABI/testing/sysfs-block         |  26 +-
 Documentation/ABI/testing/sysfs-block-device  |   2 +
 Documentation/ABI/testing/sysfs-bus-acpi      |  18 +-
 .../sysfs-bus-event_source-devices-format     |   3 +-
 .../ABI/testing/sysfs-bus-i2c-devices-pca954x |  27 +-
 Documentation/ABI/testing/sysfs-bus-iio       |  10 +
 .../sysfs-bus-iio-adc-envelope-detector       |   5 +-
 .../ABI/testing/sysfs-bus-iio-cros-ec         |   2 +-
 .../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 |  10 +-
 .../ABI/testing/sysfs-bus-iio-lptimer-stm32   |  29 ++-
 .../sysfs-bus-iio-magnetometer-hmc5843        |  19 +-
 .../sysfs-bus-iio-temperature-max31856        |  19 +-
 .../ABI/testing/sysfs-bus-iio-timer-stm32     | 114 +++++----
 .../testing/sysfs-bus-intel_th-devices-msc    |   4 +
 .../testing/sysfs-bus-pci-devices-aer_stats   | 119 +++++----
 Documentation/ABI/testing/sysfs-bus-rapidio   |  23 +-
 .../ABI/testing/sysfs-bus-thunderbolt         |  40 +--
 Documentation/ABI/testing/sysfs-bus-usb       |  30 ++-
 .../testing/sysfs-bus-usb-devices-usbsevseg   |   7 +-
 Documentation/ABI/testing/sysfs-bus-vfio-mdev |  10 +-
 Documentation/ABI/testing/sysfs-class-cxl     |  15 +-
 Documentation/ABI/testing/sysfs-class-led     |   2 +-
 Documentation/ABI/testing/sysfs-class-mic.txt |  52 ++--
 Documentation/ABI/testing/sysfs-class-ocxl    |   3 +
 Documentation/ABI/testing/sysfs-class-power   |  73 +++++-
 .../ABI/testing/sysfs-class-power-twl4030     |  33 +--
 Documentation/ABI/testing/sysfs-class-rc      |  30 ++-
 .../ABI/testing/sysfs-class-scsi_host         |   7 +-
 Documentation/ABI/testing/sysfs-class-typec   |  12 +-
 .../testing/sysfs-devices-platform-ACPI-TAD   |   4 +
 .../ABI/testing/sysfs-devices-platform-docg3  |  10 +-
 .../sysfs-devices-platform-sh_mobile_lcdc_fb  |   8 +-
 .../ABI/testing/sysfs-devices-system-cpu      |  99 +++++---
 .../ABI/testing/sysfs-devices-system-ibm-rtl  |   6 +-
 .../testing/sysfs-driver-bd9571mwv-regulator  |   4 +
 Documentation/ABI/testing/sysfs-driver-genwqe |  11 +-
 .../testing/sysfs-driver-hid-logitech-lg4ff   |  18 +-
 .../ABI/testing/sysfs-driver-hid-wiimote      |  11 +-
 .../ABI/testing/sysfs-driver-samsung-laptop   |  13 +-
 .../ABI/testing/sysfs-driver-toshiba_acpi     |  26 ++
 .../ABI/testing/sysfs-driver-toshiba_haps     |   2 +
 Documentation/ABI/testing/sysfs-driver-wacom  |   4 +-
 Documentation/ABI/testing/sysfs-firmware-acpi | 237 +++++++++---------
 .../ABI/testing/sysfs-firmware-dmi-entries    |  50 ++--
 Documentation/ABI/testing/sysfs-firmware-gsmi |   2 +-
 .../ABI/testing/sysfs-firmware-memmap         |  16 +-
 Documentation/ABI/testing/sysfs-fs-ext4       |   4 +-
 .../ABI/testing/sysfs-hypervisor-xen          |  13 +-
 .../ABI/testing/sysfs-kernel-boot_params      |  23 +-
 .../ABI/testing/sysfs-kernel-mm-hugepages     |  12 +-
 .../ABI/testing/sysfs-platform-asus-laptop    |  21 +-
 .../ABI/testing/sysfs-platform-asus-wmi       |   1 +
 Documentation/ABI/testing/sysfs-platform-at91 |  10 +-
 .../ABI/testing/sysfs-platform-eeepc-laptop   |  14 +-
 .../ABI/testing/sysfs-platform-ideapad-laptop |   9 +-
 .../sysfs-platform-intel-wmi-thunderbolt      |   1 +
 .../ABI/testing/sysfs-platform-sst-atom       |  13 +-
 .../ABI/testing/sysfs-platform-usbip-vudc     |  11 +-
 Documentation/ABI/testing/sysfs-ptp           |   2 +-
 Documentation/ABI/testing/sysfs-uevent        |  10 +-
 Documentation/Kconfig                         |  11 +
 Documentation/Makefile                        |   5 +
 Documentation/admin-guide/abi-obsolete.rst    |   1 +
 Documentation/admin-guide/abi-removed.rst     |   1 +
 Documentation/admin-guide/abi-stable.rst      |   1 +
 Documentation/admin-guide/abi-testing.rst     |   1 +
 Documentation/admin-guide/abi.rst             |   2 +-
 Documentation/sphinx/kernel_abi.py            |   8 +-
 lib/Kconfig.debug                             |   2 +
 scripts/get_abi.pl                            |  14 +-
 100 files changed, 1457 insertions(+), 905 deletions(-)
 create mode 100644 Documentation/Kconfig
Signature · 1 line
2.21.0