lkml.org 
[lkml]   [2020]   [Oct]   [6]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v5 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag
    Date
    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
    \
     
     \ /
      Last update: 2020-10-06 16:08    [W:4.392 / U:0.316 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site