1# -*- coding: utf-8; mode: python -*- 2# pylint: disable=W0141,C0113,C0103,C0325 3u""" 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 35from docutils import nodes 36from docutils.parsers.rst import directives 37 38import sphinx 39from sphinx import addnodes 40from sphinx.domains.c import c_funcptr_sig_re, c_sig_re 41from sphinx.domains.c import CObject as Base_CObject 42from sphinx.domains.c import CDomain as Base_CDomain 43from itertools import chain 44import re 45 46__version__ = '1.1' 47 48# Get Sphinx version 49major, minor, patch = sphinx.version_info[:3] 50 51# Namespace to be prepended to the full name 52namespace = 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# 58RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') 59 60def 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# 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: for 76# backward-compatibility with Sphinx < 3.0 77# 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: for 85# backward-compatibility with Sphinx < 3.0 86# 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 ones 100# 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 + n 119 120 source[0] = result 121 122# 123# Now implements support for the cdomain namespacing logic 124# 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 = True 136 ) 137 138class 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 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