summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-09-19 22:35:26 +0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-09-19 22:36:41 +0300
commit142a0e11b52c18a82c4fe55132b762005dda05c0 (patch)
treef7f86ccc559311f0ae7fe42f479bea50bc543c59 /Documentation/sphinx
parent6ff7b7aff34a4c21953ebf360d8941aeec0a215e (diff)
parent2cfd100bf2f7d979c0ecaf0298f3de2f03ac9d5d (diff)
downloadlinux-142a0e11b52c18a82c4fe55132b762005dda05c0.tar.xz
Merge tag 'docs-next' of git://git.lwn.net/linux.git into patchwork
Merge back from docs-next in order to get the cdomain extension. With such extension, the number of warnings when building docs in nitpick mode reduced from 22 to 2 warnings. * docs-next/docs-next: docs/driver-model: fix typo DMA-API-HOWTO: <asm/generic/scatterlist.h> is no more doc-rst:c-domain: function-like macros arguments doc-rst:c-domain: fix sphinx version incompatibility Documentation/filesystems: Fixed typo docs: Don't format internal MPT docs docs: split up serial-interfaces.rst docs: Pull the HSI documentation together docs: Special-case function-pointer parameters in kernel-doc docs: make kernel-doc handle varargs properly x86: fix memory ranges in mm documentation documentation/scsi: Remove nodisconnect parameter doc: ioctl: Add some clarifications to botching-up-ioctls docs: split up the driver book Docs: sphinxify device-drivers.tmpl
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/cdomain.py69
1 files changed, 66 insertions, 3 deletions
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 9eb714ada394..df0419c62096 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -1,4 +1,5 @@
# -*- coding: utf-8; mode: python -*-
+# pylint: disable=W0141,C0113,C0103,C0325
u"""
cdomain
~~~~~~~
@@ -25,15 +26,26 @@ u"""
* :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
__version__ = '1.0'
+# Get Sphinx version
+major, minor, patch = map(int, sphinx.__version__.split("."))
+
def setup(app):
app.override_domain(CDomain)
@@ -53,9 +65,54 @@ class CObject(Base_CObject):
"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. """
+
+ 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, it's 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
+
+ return fullname
+
def handle_signature(self, sig, signode):
"""Transform a C signature into RST nodes."""
- fullname = super(CObject, self).handle_signature(sig, signode)
+
+ 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"]
@@ -85,8 +142,14 @@ class CObject(Base_CObject):
indextext = self.get_index_text(name)
if indextext:
- self.indexnode['entries'].append(('single', indextext,
- targetname, '', None))
+ if major == 1 and minor < 4:
+ # indexnode's tuple changed in 1.4
+ # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
+ self.indexnode['entries'].append(
+ ('single', indextext, targetname, ''))
+ else:
+ self.indexnode['entries'].append(
+ ('single', indextext, targetname, '', None))
class CDomain(Base_CDomain):