1# SPDX-License-Identifier: GPL-2.0 2# Copyright 2019 Jonathan Corbet <corbet@lwn.net> 3# 4# Apply kernel-specific tweaks after the initial document processing 5# has been done. 6# 7from docutils import nodes 8import sphinx 9from sphinx import addnodes 10if sphinx.version_info[0] < 2 or \ 11 sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1: 12 from sphinx.environment import NoUri 13else: 14 from sphinx.errors import NoUri 15import re 16from itertools import chain 17 18# 19# Python 2 lacks re.ASCII... 20# 21try: 22 ascii_p3 = re.ASCII 23except AttributeError: 24 ascii_p3 = 0 25 26# 27# Regex nastiness. Of course. 28# Try to identify "function()" that's not already marked up some 29# other way. Sphinx doesn't like a lot of stuff right after a 30# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last 31# bit tries to restrict matches to things that won't create trouble. 32# 33RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=ascii_p3) 34 35# 36# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef 37# 38RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)', 39 flags=ascii_p3) 40 41# 42# Sphinx 3 uses a different C role for each one of struct, union, enum and 43# typedef 44# 45RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=ascii_p3) 46RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=ascii_p3) 47RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=ascii_p3) 48RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3) 49 50# 51# Detects a reference to a documentation page of the form Documentation/... with 52# an optional extension 53# 54RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)') 55 56RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') 57 58# 59# Reserved C words that we should skip when cross-referencing 60# 61Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ] 62 63 64# 65# Many places in the docs refer to common system calls. It is 66# pointless to try to cross-reference them and, as has been known 67# to happen, somebody defining a function by these names can lead 68# to the creation of incorrect and confusing cross references. So 69# just don't even try with these names. 70# 71Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', 72 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', 73 'socket' ] 74 75c_namespace = '' 76 77# 78# Detect references to commits. 79# 80RE_git = re.compile(r'commit\s+(?P<rev>[0-9a-f]{12,40})(?:\s+\(".*?"\))?', 81 flags=re.IGNORECASE | re.DOTALL) 82 83def markup_refs(docname, app, node): 84 t = node.astext() 85 done = 0 86 repl = [ ] 87 # 88 # Associate each regex with the function that will markup its matches 89 # 90 markup_func_sphinx2 = {RE_doc: markup_doc_ref, 91 RE_function: markup_c_ref, 92 RE_generic_type: markup_c_ref} 93 94 markup_func_sphinx3 = {RE_doc: markup_doc_ref, 95 RE_function: markup_func_ref_sphinx3, 96 RE_struct: markup_c_ref, 97 RE_union: markup_c_ref, 98 RE_enum: markup_c_ref, 99 RE_typedef: markup_c_ref, 100 RE_git: markup_git} 101 102 if sphinx.version_info[0] >= 3: 103 markup_func = markup_func_sphinx3 104 else: 105 markup_func = markup_func_sphinx2 106 107 match_iterators = [regex.finditer(t) for regex in markup_func] 108 # 109 # Sort all references by the starting position in text 110 # 111 sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start()) 112 for m in sorted_matches: 113 # 114 # Include any text prior to match as a normal text node. 115 # 116 if m.start() > done: 117 repl.append(nodes.Text(t[done:m.start()])) 118 119 # 120 # Call the function associated with the regex that matched this text and 121 # append its return to the text 122 # 123 repl.append(markup_func[m.re](docname, app, m)) 124 125 done = m.end() 126 if done < len(t): 127 repl.append(nodes.Text(t[done:])) 128 return repl 129 130# 131# Keep track of cross-reference lookups that failed so we don't have to 132# do them again. 133# 134failed_lookups = { } 135def failure_seen(target): 136 return (target) in failed_lookups 137def note_failure(target): 138 failed_lookups[target] = True 139 140# 141# In sphinx3 we can cross-reference to C macro and function, each one with its 142# own C role, but both match the same regex, so we try both. 143# 144def markup_func_ref_sphinx3(docname, app, match): 145 cdom = app.env.domains['c'] 146 # 147 # Go through the dance of getting an xref out of the C domain 148 # 149 base_target = match.group(2) 150 target_text = nodes.Text(match.group(0)) 151 xref = None 152 possible_targets = [base_target] 153 # Check if this document has a namespace, and if so, try 154 # cross-referencing inside it first. 155 if c_namespace: 156 possible_targets.insert(0, c_namespace + "." + base_target) 157 158 if base_target not in Skipnames: 159 for target in possible_targets: 160 if (target not in Skipfuncs) and not failure_seen(target): 161 lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) 162 lit_text += target_text 163 pxref = addnodes.pending_xref('', refdomain = 'c', 164 reftype = 'function', 165 reftarget = target, 166 modname = None, 167 classname = None) 168 # 169 # XXX The Latex builder will throw NoUri exceptions here, 170 # work around that by ignoring them. 171 # 172 try: 173 xref = cdom.resolve_xref(app.env, docname, app.builder, 174 'function', target, pxref, 175 lit_text) 176 except NoUri: 177 xref = None 178 179 if xref: 180 return xref 181 note_failure(target) 182 183 return target_text 184 185def markup_c_ref(docname, app, match): 186 class_str = {# Sphinx 2 only 187 RE_function: 'c-func', 188 RE_generic_type: 'c-type', 189 # Sphinx 3+ only 190 RE_struct: 'c-struct', 191 RE_union: 'c-union', 192 RE_enum: 'c-enum', 193 RE_typedef: 'c-type', 194 } 195 reftype_str = {# Sphinx 2 only 196 RE_function: 'function', 197 RE_generic_type: 'type', 198 # Sphinx 3+ only 199 RE_struct: 'struct', 200 RE_union: 'union', 201 RE_enum: 'enum', 202 RE_typedef: 'type', 203 } 204 205 cdom = app.env.domains['c'] 206 # 207 # Go through the dance of getting an xref out of the C domain 208 # 209 base_target = match.group(2) 210 target_text = nodes.Text(match.group(0)) 211 xref = None 212 possible_targets = [base_target] 213 # Check if this document has a namespace, and if so, try 214 # cross-referencing inside it first. 215 if c_namespace: 216 possible_targets.insert(0, c_namespace + "." + base_target) 217 218 if base_target not in Skipnames: 219 for target in possible_targets: 220 if not (match.re == RE_function and target in Skipfuncs): 221 lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) 222 lit_text += target_text 223 pxref = addnodes.pending_xref('', refdomain = 'c', 224 reftype = reftype_str[match.re], 225 reftarget = target, modname = None, 226 classname = None) 227 # 228 # XXX The Latex builder will throw NoUri exceptions here, 229 # work around that by ignoring them. 230 # 231 try: 232 xref = cdom.resolve_xref(app.env, docname, app.builder, 233 reftype_str[match.re], target, pxref, 234 lit_text) 235 except NoUri: 236 xref = None 237 238 if xref: 239 return xref 240 241 return target_text 242 243# 244# Try to replace a documentation reference of the form Documentation/... with a 245# cross reference to that page 246# 247def markup_doc_ref(docname, app, match): 248 stddom = app.env.domains['std'] 249 # 250 # Go through the dance of getting an xref out of the std domain 251 # 252 absolute = match.group(1) 253 target = match.group(2) 254 if absolute: 255 target = "/" + target 256 xref = None 257 pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc', 258 reftarget = target, modname = None, 259 classname = None, refexplicit = False) 260 # 261 # XXX The Latex builder will throw NoUri exceptions here, 262 # work around that by ignoring them. 263 # 264 try: 265 xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc', 266 target, pxref, None) 267 except NoUri: 268 xref = None 269 # 270 # Return the xref if we got it; otherwise just return the plain text. 271 # 272 if xref: 273 return xref 274 else: 275 return nodes.Text(match.group(0)) 276 277def get_c_namespace(app, docname): 278 source = app.env.doc2path(docname) 279 with open(source) as f: 280 for l in f: 281 match = RE_namespace.search(l) 282 if match: 283 return match.group(1) 284 return '' 285 286def markup_git(docname, app, match): 287 # While we could probably assume that we are running in a git 288 # repository, we can't know for sure, so let's just mechanically 289 # turn them into git.kernel.org links without checking their 290 # validity. (Maybe we can do something in the future to warn about 291 # these references if this is explicitly requested.) 292 text = match.group(0) 293 rev = match.group('rev') 294 return nodes.reference('', nodes.Text(text), 295 refuri=f'https://git.kernel.org/torvalds/c/{rev}') 296 297def auto_markup(app, doctree, name): 298 global c_namespace 299 c_namespace = get_c_namespace(app, name) 300 def text_but_not_a_reference(node): 301 # The nodes.literal test catches ``literal text``, its purpose is to 302 # avoid adding cross-references to functions that have been explicitly 303 # marked with cc:func:. 304 if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal): 305 return False 306 307 child_of_reference = False 308 parent = node.parent 309 while parent: 310 if isinstance(parent, nodes.Referential): 311 child_of_reference = True 312 break 313 parent = parent.parent 314 return not child_of_reference 315 316 # 317 # This loop could eventually be improved on. Someday maybe we 318 # want a proper tree traversal with a lot of awareness of which 319 # kinds of nodes to prune. But this works well for now. 320 # 321 for para in doctree.traverse(nodes.paragraph): 322 for node in para.traverse(condition=text_but_not_a_reference): 323 node.parent.replace(node, markup_refs(name, app, node)) 324 325def setup(app): 326 app.connect('doctree-resolved', auto_markup) 327 return { 328 'parallel_read_safe': True, 329 'parallel_write_safe': True, 330 } 331