Loading...
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
131 if (major == 1 and minor < 8):
132 app.override_domain(CDomain)
133 else:
134 app.add_domain(CDomain, override=True)
135
136 return dict(
137 version = __version__,
138 parallel_read_safe = True,
139 parallel_write_safe = True
140 )
141
142class CObject(Base_CObject):
143
144 """
145 Description of a C language object.
146 """
147 option_spec = {
148 "name" : directives.unchanged
149 }
150
151 def handle_func_like_macro(self, sig, signode):
152 u"""Handles signatures of function-like macros.
153
154 If the objtype is 'function' and the the signature ``sig`` is a
155 function-like macro, the name of the macro is returned. Otherwise
156 ``False`` is returned. """
157
158 global namespace
159
160 if not self.objtype == 'function':
161 return False
162
163 m = c_funcptr_sig_re.match(sig)
164 if m is None:
165 m = c_sig_re.match(sig)
166 if m is None:
167 raise ValueError('no match')
168
169 rettype, fullname, arglist, _const = m.groups()
170 arglist = arglist.strip()
171 if rettype or not arglist:
172 return False
173
174 arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
175 arglist = [a.strip() for a in arglist.split(",")]
176
177 # has the first argument a type?
178 if len(arglist[0].split(" ")) > 1:
179 return False
180
181 # This is a function-like macro, it's arguments are typeless!
182 signode += addnodes.desc_name(fullname, fullname)
183 paramlist = addnodes.desc_parameterlist()
184 signode += paramlist
185
186 for argname in arglist:
187 param = addnodes.desc_parameter('', '', noemph=True)
188 # separate by non-breaking space in the output
189 param += nodes.emphasis(argname, argname)
190 paramlist += param
191
192 if namespace:
193 fullname = namespace + "." + fullname
194
195 return fullname
196
197 def handle_signature(self, sig, signode):
198 """Transform a C signature into RST nodes."""
199
200 global namespace
201
202 fullname = self.handle_func_like_macro(sig, signode)
203 if not fullname:
204 fullname = super(CObject, self).handle_signature(sig, signode)
205
206 if "name" in self.options:
207 if self.objtype == 'function':
208 fullname = self.options["name"]
209 else:
210 # FIXME: handle :name: value of other declaration types?
211 pass
212 else:
213 if namespace:
214 fullname = namespace + "." + fullname
215
216 return fullname
217
218 def add_target_and_index(self, name, sig, signode):
219 # for C API items we add a prefix since names are usually not qualified
220 # by a module name and so easily clash with e.g. section titles
221 targetname = 'c.' + name
222 if targetname not in self.state.document.ids:
223 signode['names'].append(targetname)
224 signode['ids'].append(targetname)
225 signode['first'] = (not self.names)
226 self.state.document.note_explicit_target(signode)
227 inv = self.env.domaindata['c']['objects']
228 if (name in inv and self.env.config.nitpicky):
229 if self.objtype == 'function':
230 if ('c:func', name) not in self.env.config.nitpick_ignore:
231 self.state_machine.reporter.warning(
232 'duplicate C object description of %s, ' % name +
233 'other instance in ' + self.env.doc2path(inv[name][0]),
234 line=self.lineno)
235 inv[name] = (self.env.docname, self.objtype)
236
237 indextext = self.get_index_text(name)
238 if indextext:
239 self.indexnode['entries'].append(
240 ('single', indextext, targetname, '', None))
241
242class CDomain(Base_CDomain):
243
244 """C language domain."""
245 name = 'c'
246 label = 'C'
247 directives = {
248 'function': CObject,
249 'member': CObject,
250 'macro': CObject,
251 'type': CObject,
252 'var': CObject,
253 }
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
43
44__version__ = '1.0'
45
46# Get Sphinx version
47major, minor, patch = sphinx.version_info[:3]
48
49def setup(app):
50
51 if (major == 1 and minor < 8):
52 app.override_domain(CDomain)
53 else:
54 app.add_domain(CDomain, override=True)
55
56 return dict(
57 version = __version__,
58 parallel_read_safe = True,
59 parallel_write_safe = True
60 )
61
62class CObject(Base_CObject):
63
64 """
65 Description of a C language object.
66 """
67 option_spec = {
68 "name" : directives.unchanged
69 }
70
71 def handle_func_like_macro(self, sig, signode):
72 u"""Handles signatures of function-like macros.
73
74 If the objtype is 'function' and the the signature ``sig`` is a
75 function-like macro, the name of the macro is returned. Otherwise
76 ``False`` is returned. """
77
78 if not self.objtype == 'function':
79 return False
80
81 m = c_funcptr_sig_re.match(sig)
82 if m is None:
83 m = c_sig_re.match(sig)
84 if m is None:
85 raise ValueError('no match')
86
87 rettype, fullname, arglist, _const = m.groups()
88 arglist = arglist.strip()
89 if rettype or not arglist:
90 return False
91
92 arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
93 arglist = [a.strip() for a in arglist.split(",")]
94
95 # has the first argument a type?
96 if len(arglist[0].split(" ")) > 1:
97 return False
98
99 # This is a function-like macro, it's arguments are typeless!
100 signode += addnodes.desc_name(fullname, fullname)
101 paramlist = addnodes.desc_parameterlist()
102 signode += paramlist
103
104 for argname in arglist:
105 param = addnodes.desc_parameter('', '', noemph=True)
106 # separate by non-breaking space in the output
107 param += nodes.emphasis(argname, argname)
108 paramlist += param
109
110 return fullname
111
112 def handle_signature(self, sig, signode):
113 """Transform a C signature into RST nodes."""
114
115 fullname = self.handle_func_like_macro(sig, signode)
116 if not fullname:
117 fullname = super(CObject, self).handle_signature(sig, signode)
118
119 if "name" in self.options:
120 if self.objtype == 'function':
121 fullname = self.options["name"]
122 else:
123 # FIXME: handle :name: value of other declaration types?
124 pass
125 return fullname
126
127 def add_target_and_index(self, name, sig, signode):
128 # for C API items we add a prefix since names are usually not qualified
129 # by a module name and so easily clash with e.g. section titles
130 targetname = 'c.' + name
131 if targetname not in self.state.document.ids:
132 signode['names'].append(targetname)
133 signode['ids'].append(targetname)
134 signode['first'] = (not self.names)
135 self.state.document.note_explicit_target(signode)
136 inv = self.env.domaindata['c']['objects']
137 if (name in inv and self.env.config.nitpicky):
138 if self.objtype == 'function':
139 if ('c:func', name) not in self.env.config.nitpick_ignore:
140 self.state_machine.reporter.warning(
141 'duplicate C object description of %s, ' % name +
142 'other instance in ' + self.env.doc2path(inv[name][0]),
143 line=self.lineno)
144 inv[name] = (self.env.docname, self.objtype)
145
146 indextext = self.get_index_text(name)
147 if indextext:
148 if major == 1 and minor < 4:
149 # indexnode's tuple changed in 1.4
150 # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
151 self.indexnode['entries'].append(
152 ('single', indextext, targetname, ''))
153 else:
154 self.indexnode['entries'].append(
155 ('single', indextext, targetname, '', None))
156
157class CDomain(Base_CDomain):
158
159 """C language domain."""
160 name = 'c'
161 label = 'C'
162 directives = {
163 'function': CObject,
164 'member': CObject,
165 'macro': CObject,
166 'type': CObject,
167 'var': CObject,
168 }