| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Date: Fri, 2 Dec 2016 11:12:50 -0200
From: Mauro Carvalho Chehab <mchehab@...pensource.com>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab@...pensource.com>,
Mauro Carvalho Chehab <mchehab@...radead.org>,
LKML <linux-kernel@...r.kernel.org>,
Jonathan Corbet <corbet@....net>,
Mauro Carvalho Chehab <mchehab@...nel.org>,
Markus Heiser <markus.heiser@...marit.de>
Subject: [PATCH 4/4] doc-rst: add ABI documentation to the admin-guide book
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@...pensource.com>
---
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
Powered by blists - more mailing lists