summaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx/cdomain.py
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sphinx/cdomain.py')
-rw-r--r--Documentation/sphinx/cdomain.py253
1 files changed, 253 insertions, 0 deletions
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
new file mode 100644
index 0000000000..a99716bf44
--- /dev/null
+++ b/Documentation/sphinx/cdomain.py
@@ -0,0 +1,253 @@
+# -*- coding: utf-8; mode: python -*-
+# pylint: disable=W0141,C0113,C0103,C0325
+u"""
+ cdomain
+ ~~~~~~~
+
+ Replacement for the sphinx c-domain.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ List of customizations:
+
+ * Moved the *duplicate C object description* warnings for function
+ declarations in the nitpicky mode. See Sphinx documentation for
+ the config values for ``nitpick`` and ``nitpick_ignore``.
+
+ * Add option 'name' to the "c:function:" directive. With option 'name' the
+ ref-name of a function can be modified. E.g.::
+
+ .. c:function:: int ioctl( int fd, int request )
+ :name: VIDIOC_LOG_STATUS
+
+ The func-name (e.g. ioctl) remains in the output but the ref-name changed
+ from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by::
+
+ * :c:func:`VIDIOC_LOG_STATUS` or
+ * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
+
+ * Handle signatures of function-like macros well. Don't try to deduce
+ arguments types of function-like macros.
+
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+
+import sphinx
+from sphinx import addnodes
+from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
+from sphinx.domains.c import CObject as Base_CObject
+from sphinx.domains.c import CDomain as Base_CDomain
+from itertools import chain
+import re
+
+__version__ = '1.1'
+
+# Get Sphinx version
+major, minor, patch = sphinx.version_info[:3]
+
+# Namespace to be prepended to the full name
+namespace = None
+
+#
+# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
+# - Store the namespace if ".. c:namespace::" tag is found
+#
+RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
+
+def markup_namespace(match):
+ global namespace
+
+ namespace = match.group(1)
+
+ return ""
+
+#
+# Handle c:macro for function-style declaration
+#
+RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$')
+def markup_macro(match):
+ return ".. c:function:: " + match.group(1) + ' ' + match.group(2)
+
+#
+# Handle newer c domain tags that are evaluated as .. c:type: for
+# backward-compatibility with Sphinx < 3.0
+#
+RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$')
+
+def markup_ctype(match):
+ return ".. c:type:: " + match.group(2)
+
+#
+# Handle newer c domain tags that are evaluated as :c:type: for
+# backward-compatibility with Sphinx < 3.0
+#
+RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`')
+def markup_ctype_refs(match):
+ return ":c:type:`" + match.group(2) + '`'
+
+#
+# Simply convert :c:expr: and :c:texpr: into a literal block.
+#
+RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`')
+def markup_c_expr(match):
+ return '\ ``' + match.group(2) + '``\ '
+
+#
+# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones
+#
+def c_markups(app, docname, source):
+ result = ""
+ markup_func = {
+ RE_namespace: markup_namespace,
+ RE_expr: markup_c_expr,
+ RE_macro: markup_macro,
+ RE_ctype: markup_ctype,
+ RE_ctype_refs: markup_ctype_refs,
+ }
+
+ lines = iter(source[0].splitlines(True))
+ for n in lines:
+ match_iterators = [regex.finditer(n) for regex in markup_func]
+ matches = sorted(chain(*match_iterators), key=lambda m: m.start())
+ for m in matches:
+ n = n[:m.start()] + markup_func[m.re](m) + n[m.end():]
+
+ result = result + n
+
+ source[0] = result
+
+#
+# Now implements support for the cdomain namespacing logic
+#
+
+def setup(app):
+
+ # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
+ app.connect('source-read', c_markups)
+
+ if (major == 1 and minor < 8):
+ app.override_domain(CDomain)
+ else:
+ app.add_domain(CDomain, override=True)
+
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
+
+class CObject(Base_CObject):
+
+ """
+ Description of a C language object.
+ """
+ option_spec = {
+ "name" : directives.unchanged
+ }
+
+ def handle_func_like_macro(self, sig, signode):
+ u"""Handles signatures of function-like macros.
+
+ If the objtype is 'function' and the the signature ``sig`` is a
+ function-like macro, the name of the macro is returned. Otherwise
+ ``False`` is returned. """
+
+ global namespace
+
+ if not self.objtype == 'function':
+ return False
+
+ m = c_funcptr_sig_re.match(sig)
+ if m is None:
+ m = c_sig_re.match(sig)
+ if m is None:
+ raise ValueError('no match')
+
+ rettype, fullname, arglist, _const = m.groups()
+ arglist = arglist.strip()
+ if rettype or not arglist:
+ return False
+
+ arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
+ arglist = [a.strip() for a in arglist.split(",")]
+
+ # has the first argument a type?
+ if len(arglist[0].split(" ")) > 1:
+ return False
+
+ # This is a function-like macro, its arguments are typeless!
+ signode += addnodes.desc_name(fullname, fullname)
+ paramlist = addnodes.desc_parameterlist()
+ signode += paramlist
+
+ for argname in arglist:
+ param = addnodes.desc_parameter('', '', noemph=True)
+ # separate by non-breaking space in the output
+ param += nodes.emphasis(argname, argname)
+ paramlist += param
+
+ if namespace:
+ fullname = namespace + "." + fullname
+
+ return fullname
+
+ def handle_signature(self, sig, signode):
+ """Transform a C signature into RST nodes."""
+
+ global namespace
+
+ fullname = self.handle_func_like_macro(sig, signode)
+ if not fullname:
+ fullname = super(CObject, self).handle_signature(sig, signode)
+
+ if "name" in self.options:
+ if self.objtype == 'function':
+ fullname = self.options["name"]
+ else:
+ # FIXME: handle :name: value of other declaration types?
+ pass
+ else:
+ if namespace:
+ fullname = namespace + "." + fullname
+
+ return fullname
+
+ def add_target_and_index(self, name, sig, signode):
+ # for C API items we add a prefix since names are usually not qualified
+ # by a module name and so easily clash with e.g. section titles
+ targetname = 'c.' + name
+ if targetname not in self.state.document.ids:
+ signode['names'].append(targetname)
+ signode['ids'].append(targetname)
+ signode['first'] = (not self.names)
+ self.state.document.note_explicit_target(signode)
+ inv = self.env.domaindata['c']['objects']
+ if (name in inv and self.env.config.nitpicky):
+ if self.objtype == 'function':
+ if ('c:func', name) not in self.env.config.nitpick_ignore:
+ self.state_machine.reporter.warning(
+ 'duplicate C object description of %s, ' % name +
+ 'other instance in ' + self.env.doc2path(inv[name][0]),
+ line=self.lineno)
+ inv[name] = (self.env.docname, self.objtype)
+
+ indextext = self.get_index_text(name)
+ if indextext:
+ self.indexnode['entries'].append(
+ ('single', indextext, targetname, '', None))
+
+class CDomain(Base_CDomain):
+
+ """C language domain."""
+ name = 'c'
+ label = 'C'
+ directives = {
+ 'function': CObject,
+ 'member': CObject,
+ 'macro': CObject,
+ 'type': CObject,
+ 'var': CObject,
+ }