[PATCH 4/4] doc-rst: add ABI documentation to the admin-guide book

[Mauro Carvalho Chehab]

As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.

Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---
 Documentation/admin-guide/abi.rst                  |  5 ++
 Documentation/admin-guide/index.rst                |  1 +
 Documentation/conf.py                              |  2 +-
 .../sphinx/{kernel_cmd.py => kernel_abi.py}        | 78 ++++------------------
 4 files changed, 21 insertions(+), 65 deletions(-)
 create mode 100644 Documentation/admin-guide/abi.rst
 rename Documentation/sphinx/{kernel_cmd.py => kernel_abi.py} (59%)

diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst
new file mode 100644
index 000000000000..27c9657fbd4e
--- /dev/null
+++ b/Documentation/admin-guide/abi.rst
@@ -0,0 +1,5 @@
+=====================
+Linux ABI description
+=====================
+
+.. kernel-abi:: $srctree/Documentation/ABI/
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index a2a72b749861..cf11a1b5fda9 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -14,6 +14,7 @@ etc.
    :maxdepth: 1
 
    README
+   abi
    kernel-parameters
    devices
 
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 515d6149f04e..2626ac1bc5f4 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,7 @@ from load_config import loadConfig
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kernel_cmd']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kernel_abi']
 
 # The name of the math extension changed on Sphinx 1.4
 if major == 1 and minor > 3:
diff --git a/Documentation/sphinx/kernel_cmd.py b/Documentation/sphinx/kernel_abi.py
similarity index 59%
rename from Documentation/sphinx/kernel_cmd.py
rename to Documentation/sphinx/kernel_abi.py
index 43f02b067ecf..aa5d2a273049 100644
--- a/Documentation/sphinx/kernel_cmd.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -1,64 +1,31 @@
 # -*- coding: utf-8; mode: python -*-
 u"""
-    kernel-cmd
+    kernel-abi
     ~~~~~~~~~~
 
-    Implementation of the ``kernel-cmd`` reST-directive.
+    Implementation of the ``kernel-abi`` reST-directive.
 
     :copyright:  Copyright (C) 2016  Markus Heiser
+    :copyright:  Copyright (C) 2016  Mauro Carvalho Chehab
     :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
 
-    The ``kernel-cmd`` (:py:class:`KernelCmd`) directive includes contend
-    from the stdout of a comand-line.
+    The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
+    scripts/get_abi.pl script to parse the Kernel ABI files.
 
     Overview of directive's argument and options.
 
     .. code-block:: rst
 
-        .. kernel-cmd:: <command line>
-            :depends: <list of comma separated file names>
-            :code-block: <language>
+        .. kernel-abi:: <ABI directory location>
             :debug:
 
-    The argument ``<command line>`` is required, it is a command line to be
-    executed. The stdout stream of the command is captured and is inserted as
-    reST content. The command line is executed in a system shell where the PATH
-    environment is extended with the paths ::
-
-        PATH=$(srctree)/scripts:$(srctree)/Documentation/sphinx:...
-
-    ``depends <list of comma separated file names>``
-
-      If the stdout of the command line depends on files, you can add them as
-      dependency, which means: if one of the listed files is changed, the
-      sphinx-build (environment) is newly build.
-
-    ``code-block <language>``
-
-      If the called script outputs a code-block, use the ``code-block`` option
-      with an *language* as argument.  The valid values for the highlighting
-      language are:
-
-      * none (no highlighting)
-      * guess (let Pygments guess the lexer based on contents, only works
-        with certain well-recognizable languages)
-      * rest
-      * c
-      * and any other lexer alias that `Pygments
-        <http://pygments.org/docs/lexers/>`_ supports.
+    The argument ``<ABI directory location>`` is required. It contains the
+    location of the ABI files to be parsed.
 
     ``debug``
       Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
       what reST is generated.
 
-    .. warning::
-
-       The kernel-cmd directive **executes** commands, whatever poses a risk
-       (shell injection) in itself!
-
-       The command might depend on local installations, don't use commands which
-       are not available in some OS (be clear about the dependencies).
-
 """
 
 import sys
@@ -86,7 +53,7 @@ if PY3:
 
 def setup(app):
 
-    app.add_directive("kernel-cmd", KernelCmd)
+    app.add_directive("kernel-abi", KernelCmd)
     return dict(
         version = __version__
         , parallel_read_safe = True
@@ -95,7 +62,7 @@ def setup(app):
 
 class KernelCmd(Directive):
 
-    u"""KernelCmd (``kernel-cmd``) directive"""
+    u"""KernelABI (``kernel-abi``) directive"""
 
     required_arguments = 1
     optional_arguments = 0
@@ -103,15 +70,13 @@ class KernelCmd(Directive):
     final_argument_whitespace = True
 
     option_spec = {
-        "depends"   : directives.unchanged,
-        "code-block": directives.unchanged,
         "debug"     : directives.flag
     }
 
     def warn(self, message, **replace):
         replace["fname"]   = self.state.document.current_source
         replace["line_no"] = replace.get("line_no", self.lineno)
-        message = ("%(fname)s:%(line_no)s: [kernel-cmd WARN] : " + message) % replace
+        message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
         self.state.document.settings.env.app.warn(message, prefix="")
 
     def run(self):
@@ -122,25 +87,16 @@ class KernelCmd(Directive):
 
         env = doc.settings.env
         cwd = path.dirname(doc.current_source)
-        cmd = self.arguments[0]
-
-        if "depends" in self.options:
-            dep = self.options.get("depends")
-            dep = ''.join([s.strip() for s in dep.splitlines()])
-            dep = [s.strip() for s in dep.split(",")]
-            for p in dep:
-                env.note_dependency(p)
+        cmd = "get_abi.pl "
+        cmd += self.arguments[0]
 
         srctree = path.abspath(os.environ["srctree"])
 
-        # Since there is no *source* file, we use the command string as
-        # (default) filename
         fname = cmd
 
-        # extend PATH with $(srctree)/scripts:$(srctree)/Documentation/sphinx
+        # extend PATH with $(srctree)/scripts
         path_env = os.pathsep.join([
             srctree + os.sep + "scripts",
-            srctree + os.sep + "Documentation" + os.sep + "sphinx",
             os.environ["PATH"]
         ])
         shell_env = os.environ.copy()
@@ -179,12 +135,6 @@ class KernelCmd(Directive):
         content = ViewList()
         node    = nodes.section()
 
-        if "code-block" in self.options:
-            code_block = "\n\n.. code-block:: %s\n" % self.options["code-block"]
-            for l in lines.split("\n"):
-                code_block += "\n    " + l
-            lines = code_block + "\n\n"
-
         if "debug" in self.options:
             code_block = "\n\n.. code-block:: rst\n    :linenos:\n"
             for l in lines.split("\n"):
-- 
2.9.3