Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S934172AbcLBNNt (ORCPT ); Fri, 2 Dec 2016 08:13:49 -0500 Received: from bombadil.infradead.org ([198.137.202.9]:53266 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1759591AbcLBNM4 (ORCPT ); Fri, 2 Dec 2016 08:12:56 -0500 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , LKML , Jonathan Corbet , Mauro Carvalho Chehab , Markus Heiser Subject: [PATCH 4/4] doc-rst: add ABI documentation to the admin-guide book Date: Fri, 2 Dec 2016 11:12:50 -0200 Message-Id: <9b590614f4f1997af1ba2691a79ab1cfc0c36d81.1480683879.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.9.3 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 7647 Lines: 213 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 --- 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:: - :depends: - :code-block: + .. kernel-abi:: :debug: - The argument ```` 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 `` - - 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 `` - - 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 - `_ supports. + The argument ```` 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