Documentation/sphinx/kernel-doc.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 os
  31 import subprocess
  32 import sys
  33
  34 from docutils import nodes, statemachine
  35 from docutils.parsers.rst import directives
  36 from sphinx.util.compat import Directive
  37
  38 class KernelDocDirective(Directive):
  39     """Extract kernel-doc comments from the specified file"""
  40     required_argument = 1
  41     optional_arguments = 4
  42     option_spec = {
  43         'doc': directives.unchanged_required,
  44         'functions': directives.unchanged_required,
  45         'export': directives.flag,
  46         'internal': directives.flag,
  47     }
  48     has_content = False
  49
  50     def run(self):
  51         env = self.state.document.settings.env
  52         cmd = [env.config.kerneldoc_bin, '-rst']
  53
  54         filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
  55
  56         # Tell sphinx of the dependency
  57         env.note_dependency(os.path.abspath(filename))
  58
  59         tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
  60         source = filename
  61
  62         # FIXME: make this nicer and more robust against errors
  63         if 'export' in self.options:
  64             cmd += ['-export']
  65         elif 'internal' in self.options:
  66             cmd += ['-internal']
  67         elif 'doc' in self.options:
  68             cmd += ['-function', str(self.options.get('doc'))]
  69         elif 'functions' in self.options:
  70             for f in str(self.options.get('functions')).split(' '):
  71                 cmd += ['-function', f]
  72
  73         cmd += [filename]
  74
  75         try:
  76             env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
  77
  78             p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
  79             out, err = p.communicate()
  80
  81             # python2 needs conversion to unicode.
  82             # python3 with universal_newlines=True returns strings.
  83             if sys.version_info.major < 3:
  84                 out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
  85
  86             if p.returncode != 0:
  87                 sys.stderr.write(err)
  88
  89                 env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
  90                 return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
  91             elif env.config.kerneldoc_verbosity > 0:
  92                 sys.stderr.write(err)
  93
  94             lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
  95             self.state_machine.insert_input(lines, source)
  96             return []
  97         except Exception as e:
  98             env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
  99                          (" ".join(cmd), str(e)))
 100             return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
 101
 102 def setup(app):
 103     app.add_config_value('kerneldoc_bin', None, 'env')
 104     app.add_config_value('kerneldoc_srctree', None, 'env')
 105     app.add_config_value('kerneldoc_verbosity', 1, 'env')
 106
 107     app.add_directive('kernel-doc', KernelDocDirective)