summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-09-24 11:32:38 +0200
committerMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-10-15 07:49:37 +0200
commit71e552aebf260239463d348ecb75b972bee0804b (patch)
treecb1b2ddf622a87b5cf9517249bef46b76cb59921 /Documentation/sphinx
parent6e9e415854c15dbf920481eb1d245988e405bbc0 (diff)
docs: cdomain.py: add support for a new Sphinx 3.1+ tag
Since Sphinx 3.0, the C domain code was rewritten, but only after version 3.1 it got support for setting namespaces on C domains, with is something that it is required, in order to document system calls, like ioctl() and others. As part of changing the documentation subsystem to properly build with Sphinx 3.1+, add support for such new tag: .. c:namespace::" Such tag optionally replaces the optional "name" tag for functions, setting a single namespace domain for all C references found at the file. With that, it should be possible to convert existing documentation to be compatible with both Sphinx 1.x/2.x and 3.1+. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/cdomain.py55
1 files changed, 54 insertions, 1 deletions
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index cbac8e608dc4..35805c44a4fc 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -40,14 +40,56 @@ 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.0'
+__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 ""
+
+def c_markups(app, docname, source):
+ result = ""
+ markup_func = {
+ RE_namespace: markup_namespace,
+ }
+
+ 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:
@@ -75,6 +117,8 @@ class CObject(Base_CObject):
function-like macro, the name of the macro is returned. Otherwise
``False`` is returned. """
+ global namespace
+
if not self.objtype == 'function':
return False
@@ -107,11 +151,16 @@ class CObject(Base_CObject):
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)
@@ -122,6 +171,10 @@ class CObject(Base_CObject):
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):