Documentation/sphinx/cdomain.py

   1 # -*- coding: utf-8; mode: python -*-
   2 # pylint: disable=W0141,C0113,C0103,C0325
   3 u"""
   4     cdomain
   5     ~~~~~~~
   6
   7     Replacement for the sphinx c-domain.
   8
   9     :copyright:  Copyright (C) 2016  Markus Heiser
  10     :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
  11
  12     List of customizations:
  13
  14     * Moved the *duplicate C object description* warnings for function
  15       declarations in the nitpicky mode. See Sphinx documentation for
  16       the config values for ``nitpick`` and ``nitpick_ignore``.
  17
  18     * Add option 'name' to the "c:function:" directive.  With option 'name' the
  19       ref-name of a function can be modified. E.g.::
  20
  21           .. c:function:: int ioctl( int fd, int request )
  22              :name: VIDIOC_LOG_STATUS
  23
  24       The func-name (e.g. ioctl) remains in the output but the ref-name changed
  25       from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by::
  26
  27           * :c:func:`VIDIOC_LOG_STATUS` or
  28           * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
  29
  30      * Handle signatures of function-like macros well. Don't try to deduce
  31        arguments types of function-like macros.
  32
  33 """
  34
  35 from docutils import nodes
  36 from docutils.parsers.rst import directives
  37
  38 import sphinx
  39 from sphinx import addnodes
  40 from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
  41 from sphinx.domains.c import CObject as Base_CObject
  42 from sphinx.domains.c import CDomain as Base_CDomain
  43 from itertools import chain
  44 import re
  45
  46 __version__  = '1.1'
  47
  48 # Get Sphinx version
  49 major, minor, patch = sphinx.version_info[:3]
  50
  51 # Namespace to be prepended to the full name
  52 namespace = None
  53
  54 #
  55 # Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
  56 # - Store the namespace if ".. c:namespace::" tag is found
  57 #
  58 RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
  59
  60 def markup_namespace(match):
  61     global namespace
  62
  63     namespace = match.group(1)
  64
  65     return ""
  66
  67 #
  68 # Handle c:macro for function-style declaration
  69 #
  70 RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$')
  71 def markup_macro(match):
  72     return ".. c:function:: " + match.group(1) + ' ' + match.group(2)
  73
  74 #
  75 # Handle newer c domain tags that are evaluated as .. c:type: for
  76 # backward-compatibility with Sphinx < 3.0
  77 #
  78 RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$')
  79
  80 def markup_ctype(match):
  81     return ".. c:type:: " + match.group(2)
  82
  83 #
  84 # Handle newer c domain tags that are evaluated as :c:type: for
  85 # backward-compatibility with Sphinx < 3.0
  86 #
  87 RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`')
  88 def markup_ctype_refs(match):
  89     return ":c:type:`" + match.group(2) + '`'
  90
  91 #
  92 # Simply convert :c:expr: and :c:texpr: into a literal block.
  93 #
  94 RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`')
  95 def markup_c_expr(match):
  96     return '\\ ``' + match.group(2) + '``\\ '
  97
  98 #
  99 # Parse Sphinx 3.x C markups, replacing them by backward-compatible ones
 100 #
 101 def c_markups(app, docname, source):
 102     result = ""
 103     markup_func = {
 104         RE_namespace: markup_namespace,
 105         RE_expr: markup_c_expr,
 106         RE_macro: markup_macro,
 107         RE_ctype: markup_ctype,
 108         RE_ctype_refs: markup_ctype_refs,
 109     }
 110
 111     lines = iter(source[0].splitlines(True))
 112     for n in lines:
 113         match_iterators = [regex.finditer(n) for regex in markup_func]
 114         matches = sorted(chain(*match_iterators), key=lambda m: m.start())
 115         for m in matches:
 116             n = n[:m.start()] + markup_func[m.re](m) + n[m.end():]
 117
 118         result = result + n
 119
 120     source[0] = result
 121
 122 #
 123 # Now implements support for the cdomain namespacing logic
 124 #
 125
 126 def setup(app):
 127
 128     # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
 129     app.connect('source-read', c_markups)
 130     app.add_domain(CDomain, override=True)
 131
 132     return dict(
 133         version = __version__,
 134         parallel_read_safe = True,
 135         parallel_write_safe = True
 136     )
 137
 138 class CObject(Base_CObject):
 139
 140     """
 141     Description of a C language object.
 142     """
 143     option_spec = {
 144         "name" : directives.unchanged
 145     }
 146
 147     def handle_func_like_macro(self, sig, signode):
 148         u"""Handles signatures of function-like macros.
 149
 150         If the objtype is 'function' and the signature ``sig`` is a
 151         function-like macro, the name of the macro is returned. Otherwise
 152         ``False`` is returned.  """
 153
 154         global namespace
 155
 156         if not self.objtype == 'function':
 157             return False
 158
 159         m = c_funcptr_sig_re.match(sig)
 160         if m is None:
 161             m = c_sig_re.match(sig)
 162             if m is None:
 163                 raise ValueError('no match')
 164
 165         rettype, fullname, arglist, _const = m.groups()
 166         arglist = arglist.strip()
 167         if rettype or not arglist:
 168             return False
 169
 170         arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
 171         arglist = [a.strip() for a in arglist.split(",")]
 172
 173         # has the first argument a type?
 174         if len(arglist[0].split(" ")) > 1:
 175             return False
 176
 177         # This is a function-like macro, its arguments are typeless!
 178         signode  += addnodes.desc_name(fullname, fullname)
 179         paramlist = addnodes.desc_parameterlist()
 180         signode  += paramlist
 181
 182         for argname in arglist:
 183             param = addnodes.desc_parameter('', '', noemph=True)
 184             # separate by non-breaking space in the output
 185             param += nodes.emphasis(argname, argname)
 186             paramlist += param
 187
 188         if namespace:
 189             fullname = namespace + "." + fullname
 190
 191         return fullname
 192
 193     def handle_signature(self, sig, signode):
 194         """Transform a C signature into RST nodes."""
 195
 196         global namespace
 197
 198         fullname = self.handle_func_like_macro(sig, signode)
 199         if not fullname:
 200             fullname = super(CObject, self).handle_signature(sig, signode)
 201
 202         if "name" in self.options:
 203             if self.objtype == 'function':
 204                 fullname = self.options["name"]
 205             else:
 206                 # FIXME: handle :name: value of other declaration types?
 207                 pass
 208         else:
 209             if namespace:
 210                 fullname = namespace + "." + fullname
 211
 212         return fullname
 213
 214     def add_target_and_index(self, name, sig, signode):
 215         # for C API items we add a prefix since names are usually not qualified
 216         # by a module name and so easily clash with e.g. section titles
 217         targetname = 'c.' + name
 218         if targetname not in self.state.document.ids:
 219             signode['names'].append(targetname)
 220             signode['ids'].append(targetname)
 221             signode['first'] = (not self.names)
 222             self.state.document.note_explicit_target(signode)
 223             inv = self.env.domaindata['c']['objects']
 224             if (name in inv and self.env.config.nitpicky):
 225                 if self.objtype == 'function':
 226                     if ('c:func', name) not in self.env.config.nitpick_ignore:
 227                         self.state_machine.reporter.warning(
 228                             'duplicate C object description of %s, ' % name +
 229                             'other instance in ' + self.env.doc2path(inv[name][0]),
 230                             line=self.lineno)
 231             inv[name] = (self.env.docname, self.objtype)
 232
 233         indextext = self.get_index_text(name)
 234         if indextext:
 235             self.indexnode['entries'].append(
 236                     ('single', indextext, targetname, '', None))
 237
 238 class CDomain(Base_CDomain):
 239
 240     """C language domain."""
 241     name = 'c'
 242     label = 'C'
 243     directives = {
 244         'function': CObject,
 245         'member':   CObject,
 246         'macro':    CObject,
 247         'type':     CObject,
 248         'var':      CObject,
 249     }