From 58af04dff742b6b49fae3de585bdea8c77b62ddc Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 19 Oct 2016 13:44:37 +0300 Subject: Documentation/sphinx: rename kernel-doc.py to kerneldoc.py Python module names should not have hyphens per [PEP 8]. Drop the hyphen from kernel-doc.py. The extension directive remains unchanged. [PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names Reported-by: Markus Heiser Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 +- Documentation/sphinx/kernel-doc.py | 149 ------------------------------------- Documentation/sphinx/kerneldoc.py | 149 +++++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 150 deletions(-) delete mode 100644 Documentation/sphinx/kernel-doc.py create mode 100644 Documentation/sphinx/kerneldoc.py (limited to 'Documentation') diff --git a/Documentation/conf.py b/Documentation/conf.py index bf6f310e5170..4db1993658ea 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 = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py deleted file mode 100644 index d15e07f36881..000000000000 --- a/Documentation/sphinx/kernel-doc.py +++ /dev/null @@ -1,149 +0,0 @@ -# coding=utf-8 -# -# Copyright © 2016 Intel Corporation -# -# Permission is hereby granted, free of charge, to any person obtaining a -# copy of this software and associated documentation files (the "Software"), -# to deal in the Software without restriction, including without limitation -# the rights to use, copy, modify, merge, publish, distribute, sublicense, -# and/or sell copies of the Software, and to permit persons to whom the -# Software is furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice (including the next -# paragraph) shall be included in all copies or substantial portions of the -# Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS -# IN THE SOFTWARE. -# -# Authors: -# Jani Nikula -# -# Please make sure this works on both python2 and python3. -# - -import os -import subprocess -import sys -import re -import glob - -from docutils import nodes, statemachine -from docutils.statemachine import ViewList -from docutils.parsers.rst import directives -from sphinx.util.compat import Directive -from sphinx.ext.autodoc import AutodocReporter - -__version__ = '1.0' - -class KernelDocDirective(Directive): - """Extract kernel-doc comments from the specified file""" - required_argument = 1 - optional_arguments = 4 - option_spec = { - 'doc': directives.unchanged_required, - 'functions': directives.unchanged_required, - 'export': directives.unchanged, - 'internal': directives.unchanged, - } - has_content = False - - def run(self): - env = self.state.document.settings.env - cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] - - filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] - export_file_patterns = [] - - # Tell sphinx of the dependency - env.note_dependency(os.path.abspath(filename)) - - tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) - - # FIXME: make this nicer and more robust against errors - if 'export' in self.options: - cmd += ['-export'] - export_file_patterns = str(self.options.get('export')).split() - elif 'internal' in self.options: - cmd += ['-internal'] - export_file_patterns = str(self.options.get('internal')).split() - elif 'doc' in self.options: - cmd += ['-function', str(self.options.get('doc'))] - elif 'functions' in self.options: - for f in str(self.options.get('functions')).split(): - cmd += ['-function', f] - - for pattern in export_file_patterns: - for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): - env.note_dependency(os.path.abspath(f)) - cmd += ['-export-file', f] - - cmd += [filename] - - try: - env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) - - p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True) - out, err = p.communicate() - - # python2 needs conversion to unicode. - # python3 with universal_newlines=True returns strings. - if sys.version_info.major < 3: - out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8') - - if p.returncode != 0: - sys.stderr.write(err) - - env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) - return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] - elif env.config.kerneldoc_verbosity > 0: - sys.stderr.write(err) - - lines = statemachine.string2lines(out, tab_width, convert_whitespace=True) - result = ViewList() - - lineoffset = 0; - line_regex = re.compile("^#define LINENO ([0-9]+)$") - for line in lines: - match = line_regex.search(line) - if match: - # sphinx counts lines from 0 - lineoffset = int(match.group(1)) - 1 - # we must eat our comments since the upset the markup - else: - result.append(line, filename, lineoffset) - lineoffset += 1 - - node = nodes.section() - buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter - self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) - self.state.memo.title_styles, self.state.memo.section_level = [], 0 - try: - self.state.nested_parse(result, 0, node, match_titles=1) - finally: - self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf - - return node.children - - except Exception as e: # pylint: disable=W0703 - env.app.warn('kernel-doc \'%s\' processing failed with: %s' % - (" ".join(cmd), str(e))) - return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] - -def setup(app): - app.add_config_value('kerneldoc_bin', None, 'env') - app.add_config_value('kerneldoc_srctree', None, 'env') - app.add_config_value('kerneldoc_verbosity', 1, 'env') - - app.add_directive('kernel-doc', KernelDocDirective) - - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py new file mode 100644 index 000000000000..d15e07f36881 --- /dev/null +++ b/Documentation/sphinx/kerneldoc.py @@ -0,0 +1,149 @@ +# coding=utf-8 +# +# Copyright © 2016 Intel Corporation +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# +# Authors: +# Jani Nikula +# +# Please make sure this works on both python2 and python3. +# + +import os +import subprocess +import sys +import re +import glob + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives +from sphinx.util.compat import Directive +from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +class KernelDocDirective(Directive): + """Extract kernel-doc comments from the specified file""" + required_argument = 1 + optional_arguments = 4 + option_spec = { + 'doc': directives.unchanged_required, + 'functions': directives.unchanged_required, + 'export': directives.unchanged, + 'internal': directives.unchanged, + } + has_content = False + + def run(self): + env = self.state.document.settings.env + cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns = [] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(filename)) + + tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) + + # FIXME: make this nicer and more robust against errors + if 'export' in self.options: + cmd += ['-export'] + export_file_patterns = str(self.options.get('export')).split() + elif 'internal' in self.options: + cmd += ['-internal'] + export_file_patterns = str(self.options.get('internal')).split() + elif 'doc' in self.options: + cmd += ['-function', str(self.options.get('doc'))] + elif 'functions' in self.options: + for f in str(self.options.get('functions')).split(): + cmd += ['-function', f] + + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): + env.note_dependency(os.path.abspath(f)) + cmd += ['-export-file', f] + + cmd += [filename] + + try: + env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) + + p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True) + out, err = p.communicate() + + # python2 needs conversion to unicode. + # python3 with universal_newlines=True returns strings. + if sys.version_info.major < 3: + out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8') + + if p.returncode != 0: + sys.stderr.write(err) + + env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) + + lines = statemachine.string2lines(out, tab_width, convert_whitespace=True) + result = ViewList() + + lineoffset = 0; + line_regex = re.compile("^#define LINENO ([0-9]+)$") + for line in lines: + match = line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset = int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + result.append(line, filename, lineoffset) + lineoffset += 1 + + node = nodes.section() + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children + + except Exception as e: # pylint: disable=W0703 + env.app.warn('kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + +def setup(app): + app.add_config_value('kerneldoc_bin', None, 'env') + app.add_config_value('kerneldoc_srctree', None, 'env') + app.add_config_value('kerneldoc_verbosity', 1, 'env') + + app.add_directive('kernel-doc', KernelDocDirective) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) -- cgit v1.2.3