Blame view
Documentation/sphinx/kernel-doc.py
5.75 KB
c56de1db5 Documentation/sph... |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
# 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 <jani.nikula@intel.com> |
ba3501859 Documentation/sph... |
26 27 28 |
# # Please make sure this works on both python2 and python3. # |
c56de1db5 Documentation/sph... |
29 30 31 32 |
import os import subprocess import sys |
d90368f2f doc/sphinx: Track... |
33 |
import re |
03d35d9ec Documentation/sph... |
34 |
import glob |
c56de1db5 Documentation/sph... |
35 36 |
from docutils import nodes, statemachine |
16e161c8c doc/sphinx: Stop ... |
37 |
from docutils.statemachine import ViewList |
c56de1db5 Documentation/sph... |
38 39 |
from docutils.parsers.rst import directives from sphinx.util.compat import Directive |
f42ddca7b doc-rst: kernel-d... |
40 |
from sphinx.ext.autodoc import AutodocReporter |
c56de1db5 Documentation/sph... |
41 |
|
b62b9d81a docs: sphinx-exte... |
42 |
__version__ = '1.0' |
c56de1db5 Documentation/sph... |
43 44 45 46 47 48 49 |
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, |
03d35d9ec Documentation/sph... |
50 51 |
'export': directives.unchanged, 'internal': directives.unchanged, |
c56de1db5 Documentation/sph... |
52 53 54 55 56 |
} has_content = False def run(self): env = self.state.document.settings.env |
d90368f2f doc/sphinx: Track... |
57 |
cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] |
c56de1db5 Documentation/sph... |
58 59 |
filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] |
03d35d9ec Documentation/sph... |
60 |
export_file_patterns = [] |
c56de1db5 Documentation/sph... |
61 62 63 64 65 |
# 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) |
c56de1db5 Documentation/sph... |
66 67 68 69 |
# FIXME: make this nicer and more robust against errors if 'export' in self.options: cmd += ['-export'] |
03d35d9ec Documentation/sph... |
70 |
export_file_patterns = str(self.options.get('export')).split() |
c56de1db5 Documentation/sph... |
71 72 |
elif 'internal' in self.options: cmd += ['-internal'] |
03d35d9ec Documentation/sph... |
73 |
export_file_patterns = str(self.options.get('internal')).split() |
c56de1db5 Documentation/sph... |
74 75 76 |
elif 'doc' in self.options: cmd += ['-function', str(self.options.get('doc'))] elif 'functions' in self.options: |
057de5c4d Documentation/sph... |
77 |
for f in str(self.options.get('functions')).split(): |
c56de1db5 Documentation/sph... |
78 |
cmd += ['-function', f] |
03d35d9ec Documentation/sph... |
79 80 81 82 |
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] |
c56de1db5 Documentation/sph... |
83 84 85 86 87 88 89 |
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() |
ba3501859 Documentation/sph... |
90 91 92 93 |
# 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') |
c56de1db5 Documentation/sph... |
94 95 96 97 98 99 100 101 102 103 |
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) |
d90368f2f doc/sphinx: Track... |
104 105 106 107 108 109 110 111 112 113 114 |
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: |
06173fe33 Documentation/sph... |
115 |
result.append(line, filename, lineoffset) |
d90368f2f doc/sphinx: Track... |
116 |
lineoffset += 1 |
16e161c8c doc/sphinx: Stop ... |
117 118 |
node = nodes.section() |
f42ddca7b doc-rst: kernel-d... |
119 120 121 122 123 124 125 |
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 |
16e161c8c doc/sphinx: Stop ... |
126 127 |
return node.children |
f42ddca7b doc-rst: kernel-d... |
128 |
except Exception as e: # pylint: disable=W0703 |
c56de1db5 Documentation/sph... |
129 130 131 132 133 134 135 136 137 138 |
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) |
b62b9d81a docs: sphinx-exte... |
139 140 141 142 143 144 |
return dict( version = __version__, parallel_read_safe = True, parallel_write_safe = True ) |