tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: cdomain.py: extend it to handle new Sphinx 3.x tags

While most of the C domain parsing is done via kernel-doc,
some RST files use C domain tags directly.

While several of them can be removed for Sphinx < 3.0, due
to automarkup.py, and several others that could be
converted into kernel-doc markups, changes like that are
time-consuming, and may not fit all cases.

As we already have the cdomain.py for handing backward
compatibility with Sphinx versions below 3.0, let's
make it more complete, in order to cover any usage of the
newer tags outside kernel-doc.

This way, it should be feasible to use the new tags inside
the Kernel tree, without losing backward compatibility.

This should allow fixing the remaining warnings with
the Kernel tags.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Mauro Carvalho Chehab 95f49490 71e552ae

+39 -1
+39 -1
Documentation/sphinx/cdomain.py
··· 54 54 # 55 55 # Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags 56 56 # - Store the namespace if ".. c:namespace::" tag is found 57 - 57 + # 58 58 RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') 59 59 60 60 def markup_namespace(match): ··· 64 64 65 65 return "" 66 66 67 + # 68 + # Handle c:macro for function-style declaration 69 + # 70 + RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$') 71 + def markup_macro(match): 72 + return ".. c:function:: " + match.group(1) + ' ' + match.group(2) 73 + 74 + # 75 + # Handle newer c domain tags that are evaluated as .. c:type: for 76 + # backward-compatibility with Sphinx < 3.0 77 + # 78 + RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$') 79 + 80 + def markup_ctype(match): 81 + return ".. c:type:: " + match.group(2) 82 + 83 + # 84 + # Handle newer c domain tags that are evaluated as :c:type: for 85 + # backward-compatibility with Sphinx < 3.0 86 + # 87 + RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`') 88 + def markup_ctype_refs(match): 89 + return ":c:type:`" + match.group(2) + '`' 90 + 91 + # 92 + # Simply convert :c:expr: and :c:texpr: into a literal block. 93 + # 94 + RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') 95 + def markup_c_expr(match): 96 + return '\ ``' + match.group(2) + '``\ ' 97 + 98 + # 99 + # Parse Sphinx 3.x C markups, replacing them by backward-compatible ones 100 + # 67 101 def c_markups(app, docname, source): 68 102 result = "" 69 103 markup_func = { 70 104 RE_namespace: markup_namespace, 105 + RE_expr: markup_c_expr, 106 + RE_macro: markup_macro, 107 + RE_ctype: markup_ctype, 108 + RE_ctype_refs: markup_ctype_refs, 71 109 } 72 110 73 111 lines = iter(source[0].splitlines(True))