docs/sphinx/kerneldoc.py

   1 # coding=utf-8
   2 #
   3 # Copyright © 2016 Intel Corporation
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a
   6 # copy of this software and associated documentation files (the "Software"),
   7 # to deal in the Software without restriction, including without limitation
   8 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
   9 # and/or sell copies of the Software, and to permit persons to whom the
  10 # Software is furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice (including the next
  13 # paragraph) shall be included in all copies or substantial portions of the
  14 # Software.
  15 #
  16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  19 # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  22 # IN THE SOFTWARE.
  23 #
  24 # Authors:
  25 #    Jani Nikula <jani.nikula@intel.com>
  26 #
  27 # Please make sure this works on both python2 and python3.
  28 #
  29
  30 import codecs
  31 import os
  32 import subprocess
  33 import sys
  34 import re
  35 import glob
  36
  37 from docutils import nodes, statemachine
  38 from docutils.statemachine import ViewList
  39 from docutils.parsers.rst import directives, Directive
  40
  41 #
  42 # AutodocReporter is only good up to Sphinx 1.7
  43 #
  44 import sphinx
  45
  46 Use_SSI = sphinx.__version__[:3] >= '1.7'
  47 if Use_SSI:
  48     from sphinx.util.docutils import switch_source_input
  49 else:
  50     from sphinx.ext.autodoc import AutodocReporter
  51
  52 import kernellog
  53
  54 __version__  = '1.0'
  55
  56 class KernelDocDirective(Directive):
  57     """Extract kernel-doc comments from the specified file"""
  58     required_argument = 1
  59     optional_arguments = 4
  60     option_spec = {
  61         'doc': directives.unchanged_required,
  62         'functions': directives.unchanged,
  63         'export': directives.unchanged,
  64         'internal': directives.unchanged,
  65     }
  66     has_content = False
  67
  68     def run(self):
  69         env = self.state.document.settings.env
  70         cmd = env.config.kerneldoc_bin + ['-rst', '-enable-lineno']
  71
  72         # Pass the version string to kernel-doc, as it needs to use a different
  73         # dialect, depending what the C domain supports for each specific
  74         # Sphinx versions
  75         cmd += ['-sphinx-version', sphinx.__version__]
  76
  77         # Pass through the warnings-as-errors flag
  78         if env.config.kerneldoc_werror:
  79             cmd += ['-Werror']
  80
  81         filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
  82         export_file_patterns = []
  83
  84         # Tell sphinx of the dependency
  85         env.note_dependency(os.path.abspath(filename))
  86
  87         tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
  88
  89         # FIXME: make this nicer and more robust against errors
  90         if 'export' in self.options:
  91             cmd += ['-export']
  92             export_file_patterns = str(self.options.get('export')).split()
  93         elif 'internal' in self.options:
  94             cmd += ['-internal']
  95             export_file_patterns = str(self.options.get('internal')).split()
  96         elif 'doc' in self.options:
  97             cmd += ['-function', str(self.options.get('doc'))]
  98         elif 'functions' in self.options:
  99             functions = self.options.get('functions').split()
 100             if functions:
 101                 for f in functions:
 102                     cmd += ['-function', f]
 103             else:
 104                 cmd += ['-no-doc-sections']
 105
 106         for pattern in export_file_patterns:
 107             for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
 108                 env.note_dependency(os.path.abspath(f))
 109                 cmd += ['-export-file', f]
 110
 111         cmd += [filename]
 112
 113         try:
 114             kernellog.verbose(env.app,
 115                               'calling kernel-doc \'%s\'' % (" ".join(cmd)))
 116
 117             p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
 118             out, err = p.communicate()
 119
 120             out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
 121
 122             if p.returncode != 0:
 123                 sys.stderr.write(err)
 124
 125                 kernellog.warn(env.app,
 126                                'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
 127                 return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
 128             elif env.config.kerneldoc_verbosity > 0:
 129                 sys.stderr.write(err)
 130
 131             lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
 132             result = ViewList()
 133
 134             lineoffset = 0;
 135             line_regex = re.compile("^#define LINENO ([0-9]+)$")
 136             for line in lines:
 137                 match = line_regex.search(line)
 138                 if match:
 139                     # sphinx counts lines from 0
 140                     lineoffset = int(match.group(1)) - 1
 141                     # we must eat our comments since the upset the markup
 142                 else:
 143                     result.append(line, filename, lineoffset)
 144                     lineoffset += 1
 145
 146             node = nodes.section()
 147             self.do_parse(result, node)
 148
 149             return node.children
 150
 151         except Exception as e:  # pylint: disable=W0703
 152             kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' %
 153                            (" ".join(cmd), str(e)))
 154             return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
 155
 156     def do_parse(self, result, node):
 157         if Use_SSI:
 158             with switch_source_input(self.state, result):
 159                 self.state.nested_parse(result, 0, node, match_titles=1)
 160         else:
 161             save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
 162             self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
 163             self.state.memo.title_styles, self.state.memo.section_level = [], 0
 164             try:
 165                 self.state.nested_parse(result, 0, node, match_titles=1)
 166             finally:
 167                 self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save
 168
 169
 170 def setup(app):
 171     app.add_config_value('kerneldoc_bin', None, 'env')
 172     app.add_config_value('kerneldoc_srctree', None, 'env')
 173     app.add_config_value('kerneldoc_verbosity', 1, 'env')
 174     app.add_config_value('kerneldoc_werror', 0, 'env')
 175
 176     app.add_directive('kernel-doc', KernelDocDirective)
 177
 178     return dict(
 179         version = __version__,
 180         parallel_read_safe = True,
 181         parallel_write_safe = True
 182     )