From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
"Jonathan Corbet" <corbet@lwn.net>,
linux-kernel@vger.kernel.org
Subject: [PATCH v3 1/8] docs: cdomain.py: add support for a new Sphinx 3.1+ tag
Date: Fri, 25 Sep 2020 08:30:39 +0200 [thread overview]
Message-ID: <b0a9050522c272c59b3d37930d88c20dc5ad4e97.1601014299.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1601014299.git.mchehab+huawei@kernel.org>
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>
---
Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++-
1 file changed, 54 insertions(+), 1 deletion(-)
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):
--
2.26.2
next prev parent reply other threads:[~2020-09-25 6:31 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-25 6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-25 6:30 ` Mauro Carvalho Chehab [this message]
2020-09-25 6:30 ` [PATCH v3 2/8] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
2020-09-25 12:12 ` [PATCH v3.1 " Mauro Carvalho Chehab
2020-09-25 6:30 ` [PATCH v3 3/8] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
2020-09-25 6:30 ` [PATCH v3 4/8] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-25 6:30 ` [PATCH v3 5/8] media: docs: make V4L documents more " Mauro Carvalho Chehab
2020-09-25 6:30 ` [PATCH v3 6/8] media: docs: make DVB " Mauro Carvalho Chehab
2020-09-25 6:30 ` [PATCH v3 7/8] media: docs: make MC " Mauro Carvalho Chehab
2020-09-25 6:30 ` [PATCH v3 8/8] media: docs: make RC " Mauro Carvalho Chehab
2020-09-25 7:31 ` [PATCH v3 0/8] Improve support for building docs " Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=b0a9050522c272c59b3d37930d88c20dc5ad4e97.1601014299.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).