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 He
10 :license: GPL Version 2, June 1991 see
11
12 List of customizations:
13
14 * Moved the *duplicate C object descriptio
15 declarations in the nitpicky mode. See S
16 the config values for ``nitpick`` and ``
17
18 * Add option 'name' to the "c:function:" d
19 ref-name of a function can be modified.
20
21 .. c:function:: int ioctl( int fd, i
22 :name: VIDIOC_LOG_STATUS
23
24 The func-name (e.g. ioctl) remains in th
25 from 'ioctl' to 'VIDIOC_LOG_STATUS'. The
26
27 * :c:func:`VIDIOC_LOG_STATUS` or
28 * :any:`VIDIOC_LOG_STATUS` (``:any:`
29
30 * Handle signatures of function-like macr
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,
41 from sphinx.domains.c import CObject as Base_C
42 from sphinx.domains.c import CDomain as Base_C
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
56 # - Store the namespace if ".. c:namespace::"
57 #
58 RE_namespace = re.compile(r'^\s*..\s*c:namespa
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 declaratio
69 #
70 RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(
71 def markup_macro(match):
72 return ".. c:function:: " + match.group(1)
73
74 #
75 # Handle newer c domain tags that are evaluate
76 # backward-compatibility with Sphinx < 3.0
77 #
78 RE_ctype = re.compile(r'^\s*..\s*c:(struct|uni
79
80 def markup_ctype(match):
81 return ".. c:type:: " + match.group(2)
82
83 #
84 # Handle newer c domain tags that are evaluate
85 # backward-compatibility with Sphinx < 3.0
86 #
87 RE_ctype_refs = re.compile(r':c:(var|struct|un
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
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 b
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) f
114 matches = sorted(chain(*match_iterator
115 for m in matches:
116 n = n[:m.start()] + markup_func[m.
117
118 result = result + n
119
120 source[0] = result
121
122 #
123 # Now implements support for the cdomain names
124 #
125
126 def setup(app):
127
128 # Handle easy Sphinx 3.1+ simple new tags:
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, sign
148 u"""Handles signatures of function-lik
149
150 If the objtype is 'function' and the s
151 function-like macro, the name of the m
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
166 arglist = arglist.strip()
167 if rettype or not arglist:
168 return False
169
170 arglist = arglist.replace('`', '').rep
171 arglist = [a.strip() for a in arglist.
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 a
178 signode += addnodes.desc_name(fullnam
179 paramlist = addnodes.desc_parameterlis
180 signode += paramlist
181
182 for argname in arglist:
183 param = addnodes.desc_parameter(''
184 # separate by non-breaking space i
185 param += nodes.emphasis(argname, a
186 paramlist += param
187
188 if namespace:
189 fullname = namespace + "." + fulln
190
191 return fullname
192
193 def handle_signature(self, sig, signode):
194 """Transform a C signature into RST no
195
196 global namespace
197
198 fullname = self.handle_func_like_macro
199 if not fullname:
200 fullname = super(CObject, self).ha
201
202 if "name" in self.options:
203 if self.objtype == 'function':
204 fullname = self.options["name"
205 else:
206 # FIXME: handle :name: value o
207 pass
208 else:
209 if namespace:
210 fullname = namespace + "." + f
211
212 return fullname
213
214 def add_target_and_index(self, name, sig,
215 # for C API items we add a prefix sinc
216 # by a module name and so easily clash
217 targetname = 'c.' + name
218 if targetname not in self.state.docume
219 signode['names'].append(targetname
220 signode['ids'].append(targetname)
221 signode['first'] = (not self.names
222 self.state.document.note_explicit_
223 inv = self.env.domaindata['c']['ob
224 if (name in inv and self.env.confi
225 if self.objtype == 'function':
226 if ('c:func', name) not in
227 self.state_machine.rep
228 'duplicate C objec
229 'other instance in
230 line=self.lineno)
231 inv[name] = (self.env.docname, sel
232
233 indextext = self.get_index_text(name)
234 if indextext:
235 self.indexnode['entries'].append(
236 ('single', indextext, targ
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 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.