Commit 71e552ae authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent 6e9e4158

Documentation/sphinx/cdomain.py

+54 −1
Original line number Diff line number Diff line
@@ -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):

CRA Git | Maintained and supported by SUSTech CRA and CCSE