250 lines · python
1# -*- coding: utf-8; mode: python -*-2# pylint: disable=W0141,C0113,C0103,C03253u"""4 cdomain5 ~~~~~~~6 7 Replacement for the sphinx c-domain.8 9 :copyright: Copyright (C) 2016 Markus Heiser10 :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 function15 declarations in the nitpicky mode. See Sphinx documentation for16 the config values for ``nitpick`` and ``nitpick_ignore``.17 18 * Add option 'name' to the "c:function:" directive. With option 'name' the19 ref-name of a function can be modified. E.g.::20 21 .. c:function:: int ioctl( int fd, int request )22 :name: VIDIOC_LOG_STATUS23 24 The func-name (e.g. ioctl) remains in the output but the ref-name changed25 from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by::26 27 * :c:func:`VIDIOC_LOG_STATUS` or28 * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)29 30 * Handle signatures of function-like macros well. Don't try to deduce31 arguments types of function-like macros.32 33"""34 35from docutils import nodes36from docutils.parsers.rst import directives37 38import sphinx39from sphinx import addnodes40from sphinx.domains.c import c_funcptr_sig_re, c_sig_re41from sphinx.domains.c import CObject as Base_CObject42from sphinx.domains.c import CDomain as Base_CDomain43from itertools import chain44import re45 46__version__ = '1.1'47 48# Get Sphinx version49major, minor, patch = sphinx.version_info[:3]50 51# Namespace to be prepended to the full name52namespace = None53 54#55# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags56# - Store the namespace if ".. c:namespace::" tag is found57#58RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')59 60def markup_namespace(match):61 global namespace62 63 namespace = match.group(1)64 65 return ""66 67#68# Handle c:macro for function-style declaration69#70RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$')71def 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: for76# backward-compatibility with Sphinx < 3.077#78RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$')79 80def markup_ctype(match):81 return ".. c:type:: " + match.group(2)82 83#84# Handle newer c domain tags that are evaluated as :c:type: for85# backward-compatibility with Sphinx < 3.086#87RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`')88def 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#94RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`')95def markup_c_expr(match):96 return '\\ ``' + match.group(2) + '``\\ '97 98#99# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones100#101def 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 + n119 120 source[0] = result121 122#123# Now implements support for the cdomain namespacing logic124#125 126def 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 = True136 )137 138class CObject(Base_CObject):139 140 """141 Description of a C language object.142 """143 option_spec = {144 "name" : directives.unchanged145 }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 a151 function-like macro, the name of the macro is returned. Otherwise152 ``False`` is returned. """153 154 global namespace155 156 if not self.objtype == 'function':157 return False158 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 False169 170 arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup171 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 False176 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 += paramlist181 182 for argname in arglist:183 param = addnodes.desc_parameter('', '', noemph=True)184 # separate by non-breaking space in the output185 param += nodes.emphasis(argname, argname)186 paramlist += param187 188 if namespace:189 fullname = namespace + "." + fullname190 191 return fullname192 193 def handle_signature(self, sig, signode):194 """Transform a C signature into RST nodes."""195 196 global namespace197 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 pass208 else:209 if namespace:210 fullname = namespace + "." + fullname211 212 return fullname213 214 def add_target_and_index(self, name, sig, signode):215 # for C API items we add a prefix since names are usually not qualified216 # by a module name and so easily clash with e.g. section titles217 targetname = 'c.' + name218 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 238class 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 }250