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: automarkup.py: Add cross-reference for parametrized C macros

Sphinx 3 added support for declaring C macros with parameters using the
:c:macro role.

To support automarkup for both functions and parametrized macros using
the same regex (words ending in ()), try to cross-reference to both, and
only fall back to regular text if neither exist.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

authored by

Nícolas F. R. A. Prado and committed by
Mauro Carvalho Chehab c51d9b04 3050edfd

+42 -7
+42 -7
Documentation/sphinx/automarkup.py
··· 74 74 RE_generic_type: markup_c_ref} 75 75 76 76 markup_func_sphinx3 = {RE_doc: markup_doc_ref, 77 - RE_function: markup_c_ref, 77 + RE_function: markup_func_ref_sphinx3, 78 78 RE_struct: markup_c_ref, 79 79 RE_union: markup_c_ref, 80 80 RE_enum: markup_c_ref, ··· 109 109 return repl 110 110 111 111 # 112 - # Try to replace a C reference (function() or struct/union/enum/typedef 113 - # type_name) with an appropriate cross reference. 112 + # In sphinx3 we can cross-reference to C macro and function, each one with its 113 + # own C role, but both match the same regex, so we try both. 114 114 # 115 + def markup_func_ref_sphinx3(docname, app, match): 116 + class_str = ['c-func', 'c-macro'] 117 + reftype_str = ['function', 'macro'] 118 + 119 + cdom = app.env.domains['c'] 120 + # 121 + # Go through the dance of getting an xref out of the C domain 122 + # 123 + target = match.group(2) 124 + target_text = nodes.Text(match.group(0)) 125 + xref = None 126 + if not (target in Skipfuncs or target in Skipnames): 127 + for class_s, reftype_s in zip(class_str, reftype_str): 128 + lit_text = nodes.literal(classes=['xref', 'c', class_s]) 129 + lit_text += target_text 130 + pxref = addnodes.pending_xref('', refdomain = 'c', 131 + reftype = reftype_s, 132 + reftarget = target, modname = None, 133 + classname = None) 134 + # 135 + # XXX The Latex builder will throw NoUri exceptions here, 136 + # work around that by ignoring them. 137 + # 138 + try: 139 + xref = cdom.resolve_xref(app.env, docname, app.builder, 140 + reftype_s, target, pxref, 141 + lit_text) 142 + except NoUri: 143 + xref = None 144 + 145 + if xref: 146 + return xref 147 + 148 + return target_text 149 + 115 150 def markup_c_ref(docname, app, match): 116 - class_str = {RE_function: 'c-func', 117 - # Sphinx 2 only 151 + class_str = {# Sphinx 2 only 152 + RE_function: 'c-func', 118 153 RE_generic_type: 'c-type', 119 154 # Sphinx 3+ only 120 155 RE_struct: 'c-struct', ··· 157 122 RE_enum: 'c-enum', 158 123 RE_typedef: 'c-type', 159 124 } 160 - reftype_str = {RE_function: 'function', 161 - # Sphinx 2 only 125 + reftype_str = {# Sphinx 2 only 126 + RE_function: 'function', 162 127 RE_generic_type: 'type', 163 128 # Sphinx 3+ only 164 129 RE_struct: 'struct',