* [PATCH 1/4] doc-rst: customize RTD theme; literal-block
2016-12-02 13:12 [PATCH 0/4] Add ABI to the Documentation's admin guide Mauro Carvalho Chehab
@ 2016-12-02 13:12 ` Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 2/4] doc-rst: reST-directive kernel-cmd / include contentent from scripts Mauro Carvalho Chehab
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2016-12-02 13:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Markus Heiser, Mauro Carvalho Chehab, LKML, Jonathan Corbet,
Mauro Carvalho Chehab, Hans Verkuil, Mauro Carvalho Chehab
From: Markus Heiser <markus.heiser@darmarIT.de>
From: Markus Heiser <markus.heiser@darmarIT.de>
Format the literal-block like other code-block elements, with 12px and a
line-high of 1.5.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/sphinx-static/theme_overrides.css | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index d5764a4de5a2..7033d4c05e42 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -69,4 +69,11 @@
.rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
color: inherit;
}
+
+ /* literal blocks (e.g. parsed-literal directive) */
+
+ pre.literal-block {
+ font-size: 12px;
+ line-height: 1.5;
+ }
}
--
2.9.3
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 2/4] doc-rst: reST-directive kernel-cmd / include contentent from scripts
2016-12-02 13:12 [PATCH 0/4] Add ABI to the Documentation's admin guide Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 1/4] doc-rst: customize RTD theme; literal-block Mauro Carvalho Chehab
@ 2016-12-02 13:12 ` Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 3/4] scripts: add an script to parse the ABI files Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 4/4] doc-rst: add ABI documentation to the admin-guide book Mauro Carvalho Chehab
3 siblings, 0 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2016-12-02 13:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Markus Heiser, Mauro Carvalho Chehab, LKML, Jonathan Corbet,
Mauro Carvalho Chehab, Mauro Carvalho Chehab
From: Markus Heiser <markus.heiser@darmarIT.de>
From: Markus Heiser <markus.heiser@darmarIT.de>
The ``kernel-cmd`` directive includes contend from the stdout of a
command-line. With the ``kernel-cmd`` directive we can include the
output of any (Perl or whatever) script. This is a more general solution
for other workarounds like the "kernel_include + parseheaders" solution.
Overview of directive's argument and options.
.. code-block:: rst
.. kernel-cmd:: <command line>
:depends: <list of comma separated file names>
:code-block: <language>
: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:...
A very simple example, which includes the output as ``code-block``::
.. kernel-cmd:: ls -la $srctree
:code-block: sh
The ``code-block`` is optional, leaving it will include the output as
pure (hopefully well) formated reST.
.. 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).
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/conf.py | 2 +-
Documentation/sphinx/kernel_cmd.py | 205 +++++++++++++++++++++++++++++++++++++
2 files changed, 206 insertions(+), 1 deletion(-)
create mode 100644 Documentation/sphinx/kernel_cmd.py
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1ac958c0333d..515d6149f04e 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']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kernel_cmd']
# 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_cmd.py
new file mode 100644
index 000000000000..43f02b067ecf
--- /dev/null
+++ b/Documentation/sphinx/kernel_cmd.py
@@ -0,0 +1,205 @@
+# -*- coding: utf-8; mode: python -*-
+u"""
+ kernel-cmd
+ ~~~~~~~~~~
+
+ Implementation of the ``kernel-cmd`` reST-directive.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :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.
+
+ Overview of directive's argument and options.
+
+ .. code-block:: rst
+
+ .. kernel-cmd:: <command line>
+ :depends: <list of comma separated file names>
+ :code-block: <language>
+ :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.
+
+ ``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
+import os
+from os import path
+import subprocess
+
+from sphinx.ext.autodoc import AutodocReporter
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
+from docutils.utils.error_reporting import ErrorString
+
+
+__version__ = '1.0'
+
+# We can't assume that six is installed
+PY3 = sys.version_info[0] == 3
+PY2 = sys.version_info[0] == 2
+if PY3:
+ # pylint: disable=C0103, W0622
+ unicode = str
+ basestring = str
+
+def setup(app):
+
+ app.add_directive("kernel-cmd", KernelCmd)
+ return dict(
+ version = __version__
+ , parallel_read_safe = True
+ , parallel_write_safe = True
+ )
+
+class KernelCmd(Directive):
+
+ u"""KernelCmd (``kernel-cmd``) directive"""
+
+ required_arguments = 1
+ optional_arguments = 0
+ has_content = False
+ 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
+ self.state.document.settings.env.app.warn(message, prefix="")
+
+ def run(self):
+
+ doc = self.state.document
+ if not doc.settings.file_insertion_enabled:
+ raise self.warning("docutils: file insertion disabled")
+
+ 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)
+
+ 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
+ path_env = os.pathsep.join([
+ srctree + os.sep + "scripts",
+ srctree + os.sep + "Documentation" + os.sep + "sphinx",
+ os.environ["PATH"]
+ ])
+ shell_env = os.environ.copy()
+ shell_env["PATH"] = path_env
+ shell_env["srctree"] = srctree
+
+ lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+ nodeList = self.nestedParse(lines, fname)
+ return nodeList
+
+ def runCmd(self, cmd, **kwargs):
+ u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+ try:
+ proc = subprocess.Popen(
+ cmd
+ , stdout = subprocess.PIPE
+ , stderr = subprocess.PIPE
+ , universal_newlines = True
+ , **kwargs
+ )
+ out, err = proc.communicate()
+ if err:
+ self.warn(err)
+ if proc.returncode != 0:
+ raise self.severe(
+ u"command '%s' failed with return code %d"
+ % (cmd, proc.returncode)
+ )
+ except OSError as exc:
+ raise self.severe(u"problems with '%s' directive: %s."
+ % (self.name, ErrorString(exc)))
+ return unicode(out)
+
+ def nestedParse(self, lines, fname):
+ 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"):
+ code_block += "\n " + l
+ lines = code_block + "\n\n"
+
+ for c, l in enumerate(lines.split("\n")):
+ content.append(l, fname, c)
+
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+ return node.children
--
2.9.3
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 3/4] scripts: add an script to parse the ABI files
2016-12-02 13:12 [PATCH 0/4] Add ABI to the Documentation's admin guide Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 1/4] doc-rst: customize RTD theme; literal-block Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 2/4] doc-rst: reST-directive kernel-cmd / include contentent from scripts Mauro Carvalho Chehab
@ 2016-12-02 13:12 ` Mauro Carvalho Chehab
2016-12-02 13:12 ` [PATCH 4/4] doc-rst: add ABI documentation to the admin-guide book Mauro Carvalho Chehab
3 siblings, 0 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2016-12-02 13:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, LKML,
Jonathan Corbet, Mauro Carvalho Chehab
Add a script to parse the Documentation/ABI files and produce
an output with all entries inside an ABI (sub)directory.
Right now, it outputs its contents on ReST format. It shouldn't
be hard to make it produce other kind of outputs, since the ABI
file parser is implemented in separate than the output generator.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/get_abi.pl | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 212 insertions(+)
create mode 100755 scripts/get_abi.pl
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
new file mode 100755
index 000000000000..f7c9944a833c
--- /dev/null
+++ b/scripts/get_abi.pl
@@ -0,0 +1,212 @@
+#!/usr/bin/perl
+
+use strict;
+use Pod::Usage;
+use Getopt::Long;
+use File::Find;
+use Fcntl ':mode';
+
+my $help;
+my $man;
+my $debug;
+
+GetOptions(
+ "debug|d+" => \$debug,
+ 'help|?' => \$help,
+ man => \$man
+) or pod2usage(2);
+
+pod2usage(1) if $help;
+pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+pod2usage(2) if (scalar @ARGV != 1);
+
+my ($prefix) = @ARGV;
+
+require Data::Dumper if ($debug);
+
+my %data;
+
+#
+# Displays an error message, printing file name and line
+#
+sub parse_error($$$$) {
+ my ($file, $ln, $msg, $data) = @_;
+
+ print STDERR "file $file#$ln: $msg at\n\t$data";
+}
+
+#
+# Parse an ABI file, storing its contents at %data
+#
+sub parse_abi {
+ my $file = $File::Find::name;
+
+ my $mode = (stat($file))[2];
+ return if ($mode & S_IFDIR);
+ return if ($file =~ m,/README,);
+
+ my $name = $file;
+ $name =~ s,.*/,,;
+
+ my $type = $file;
+ $type =~ s,.*/(.*)/.*,$1,;
+
+ my $what;
+ my $new_what;
+ my $tag;
+ my $ln;
+
+ print STDERR "Opening $file\n" if ($debug > 1);
+ open IN, $file;
+ while(<IN>) {
+ $ln++;
+ if (m/^(\S+):\s*(.*)/i) {
+ my $new_tag = lc($1);
+ my $content = $2;
+
+ if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) {
+ if ($tag eq "description") {
+ $data{$what}->{$tag} .= "\n$content";;
+ $data{$what}->{$tag} =~ s/\n+$//;
+ next;
+ } else {
+ parse_error($file, $ln, "tag '$tag' is invalid", $_);
+ }
+ }
+
+ if ($new_tag =~ m/what/) {
+ if ($tag =~ m/what/) {
+ $what .= ", " . $content;
+ } else {
+ $what = $content;
+ $new_what = 1;
+ }
+ $tag = $new_tag;
+ next;
+ }
+
+ $tag = $new_tag;
+
+ if ($new_what) {
+ $new_what = 0;
+
+ $data{$what}->{type} = $type;
+ $data{$what}->{file} = $name;
+ print STDERR "\twhat: $what\n" if ($debug > 1);
+ }
+
+ if (!$what) {
+ parse_error($file, $ln, "'What:' should come first:", $_);
+ next;
+ }
+ $data{$what}->{$tag} = $content;
+ next;
+ }
+
+ # Silently ignore any headers before the database
+ next if (!$tag);
+
+ if (m/^\s*(.*)/) {
+ $data{$what}->{$tag} .= "\n$1";
+ $data{$what}->{$tag} =~ s/\n+$//;
+ next;
+ }
+
+ # Everything else is error
+ parse_error($file, $ln, "Unexpected line:", $_);
+ }
+ close IN;
+}
+
+# Outputs the output on ReST format
+sub output_rest {
+ foreach my $what (sort keys %data) {
+ my $type = $data{$what}->{type};
+ my $file = $data{$what}->{file};
+
+ my $w = $what;
+ $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+
+ print "$w\n\n";
+ print "- defined on file $file (type: $type)\n\n::\n\n";
+
+ my $desc = $data{$what}->{description};
+ $desc =~ s/^\s+//;
+
+ # Remove title markups from the description, as they won't work
+ $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
+
+ # put everything inside a code block
+ $desc =~ s/\n/\n /g;
+
+
+ if (!($desc =~ /^\s*$/)) {
+ print " $desc\n\n";
+ } else {
+ print " DESCRIPTION MISSING\n\n";
+ }
+ }
+}
+
+#
+# Parses all ABI files located at $prefix dir
+#
+find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
+
+print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
+
+#
+# Outputs an ReST file with the ABI contents
+#
+output_rest
+
+
+__END__
+
+=head1 NAME
+
+abi_book.pl - parse the Linux ABI files and produce a ReST book.
+
+=head1 SYNOPSIS
+
+B<abi_book.pl> [--debug] <ABI_DIR>]
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<--debug>
+
+Put the script in verbose mode, useful for debugging. Can be called multiple
+times, to increase verbosity.
+
+=item B<--help>
+
+Prints a brief help message and exits.
+
+=item B<--man>
+
+Prints the manual page and exits.
+
+=back
+
+=head1 DESCRIPTION
+
+Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI)
+and produce a ReST book containing the Linux ABI.
+
+=head1 BUGS
+
+Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+=cut
--
2.9.3
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 4/4] doc-rst: add ABI documentation to the admin-guide book
2016-12-02 13:12 [PATCH 0/4] Add ABI to the Documentation's admin guide Mauro Carvalho Chehab
` (2 preceding siblings ...)
2016-12-02 13:12 ` [PATCH 3/4] scripts: add an script to parse the ABI files Mauro Carvalho Chehab
@ 2016-12-02 13:12 ` Mauro Carvalho Chehab
3 siblings, 0 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2016-12-02 13:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, LKML,
Jonathan Corbet, Mauro Carvalho Chehab, Markus Heiser
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@s-opensource.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
^ permalink raw reply related [flat|nested] 5+ messages in thread