Skip to content

Add the ABI documentation to the admin guide

Mauro Carvalho Chehab linux-doc lkml 1 version New

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest12 patches 0 repliesNew

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/12scripts/get_abi.pl: change script to allow parsing in ReST modescripts/get_abi.pl+48 -260 replies
2/12scripts/get_abi.pl: fix parsing on ReST modescripts/get_abi.pl+14 -160 replies
3/12scripts/get_abi.pl: Allow optionally record from where a line came fromscripts/get_abi.pl+21 -10 replies
4/12docs: kernellog.py: add support for info()Documentation/sphinx/kernellog.py+5 -10 replies
5/12docs: kernel_abi.py: add a script to parse ABI documentationDocumentation/sphinx/kernel_abi.py+155 -00 replies
6/12docs: kernel_abi.py: fix UTF-8 supportDocumentation/sphinx/kernel_abi.py+7 -130 replies
7/12docs: kernel_abi.py: make it compatible with Sphinx 1.7+Documentation/sphinx/kernel_abi.py+27 -120 replies
8/12docs: kernel_abi.py: Update copyrightsDocumentation/sphinx/kernel_abi.py+2 -10 replies
9/12docs: kernel_abi.py: add a SPDX header fileDocumentation/sphinx/kernel_abi.py+1 -00 replies
10/12docs: kernel_abi.py: use --enable-lineno for get_abi.plDocumentation/sphinx/kernel_abi.py+14 -40 replies
11/12docs: kernel_abi.py: Handle with a lazy Sphinx parserDocumentation/sphinx/kernel_abi.py+26 -130 replies
12/12docs: add ABI documentation to the admin-guide bookDocumentation/admin-guide/abi-obsolete.rst Documentation/admin-guide/abi-removed.rst Documentation/admin-guide/abi-stable.rst +4 more+59 -10 replies

Reviews trailers per patch

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

Read the v1 thread

Cover letter [PATCH 00/12] Add the ABI documentation to the admin guide

Hi Greg/Jon,

That's the rebased patches with add the ABI documentation to the admin-guide. It is rebased on the top of driver-core/driver-core-next, and it can work both on the "old" mode, where the scripts will avoid codes that would cause troubles for ReST, or at the new mode, with parses the description to the ReST output untouched.

Patches 1 to 3 improves the get_abi.pl for it to parse ReST format, and to report where the errors/warnings occur at the ABI file.

Patch 4 is implements support for a Sphinx log facility (info).

Patches 5 to 10 adds the new kernel ABI extension, making it ready to parse files in ether "normal" or "rst-source" mode.

Patch 11 addresses a Sphinx issue, with is there since old vesions, but it gets worse on Sphins 2.0: basically, the ReST parser is lazy:
if it receives too much stuff, it silently ignores the end of the content. So, the extension needs to split the content on small chunks.

IMO, it is safe to apply patches 1 to 11 via Greg's tree. The only potential conflict would be at patch 4, but looking at docs-next, I don't see any changes at Documentation/scripts/kernelog.py.

Patch 12 actually enables everything.

If Patch 12 gets merged via Greg's tree, it may rise a single-line trivial conflict with docs-next, as it will be adding kernel_abi to the list of extensions at Documentation/conf.py, and Jon is likely adding another extension. too.

So, it could be wise postpone patch 12 to be merged after both trees got merged upstream.

Patch 12 adds ABI with ReST-scaping code. I'll submit soon a second version for the RFC patches with turns it to "clean" mode.

The entire ABI series (plus Documentation/features) is at:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.2

And the ReST output (with Sphinx 2.0 - with IMO provides a nicer output) is at:

https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html

Mauro Carvalho Chehab (12):
scripts/get_abi.pl: change script to allow parsing in ReST mode scripts/get_abi.pl: fix parsing on ReST mode scripts/get_abi.pl: Allow optionally record from where a line came
from
docs: kernellog.py: add support for info()
docs: kernel_abi.py: add a script to parse ABI documentation
docs: kernel_abi.py: fix UTF-8 support
docs: kernel_abi.py: make it compatible with Sphinx 1.7+
docs: kernel_abi.py: Update copyrights
docs: kernel_abi.py: add a SPDX header file
docs: kernel_abi.py: use --enable-lineno for get_abi.pl
docs: kernel_abi.py: Handle with a lazy Sphinx parser
docs: add ABI documentation to the admin-guide book

 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         | 189 +++++++++++++++++++++
 Documentation/sphinx/kernellog.py          |   6 +-
 scripts/get_abi.pl                         | 104 ++++++++----
 10 files changed, 325 insertions(+), 34 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
Signature · 1 line
2.21.0