Documentation/sphinx/automarkup.py

1 # SPDX-License-Identifier: GPL-2.0
4 # Apply kernel-specific tweaks after the initial document processing
23 RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
26 # Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
28 RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
32 # Sphinx 3 uses a different C role for each one of struct, union, enum and
35 RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
36 RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
37 RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
38 RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
44 RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')
45 RE_abi_file = re.compile(r'(\bDocumentation/ABI/[\w\-/]+)')
46 RE_abi_symbol = re.compile(r'(\b/(sys|config|proc)/[\w\-/]+)')
51 # Reserved C words that we should skip when cross-referencing
57 # Many places in the docs refer to common system calls.  It is
58 # pointless to try to cross-reference them and, as has been known
60 # to the creation of incorrect and confusing cross references.  So
72 RE_git = re.compile(r'commit\s+(?P<rev>[0-9a-f]{12,40})(?:\s+\(".*?"\))?',
93     match_iterators = [regex.finditer(t) for regex in markup_func]
95     # Sort all references by the starting position in text
98     for m in sorted_matches:
106         # Call the function associated with the regex that matched this text and
117 # Keep track of cross-reference lookups that failed so we don't have to
122     return (target) in failed_lookups
127 # In sphinx3 we can cross-reference to C macro and function, each one with its
139     # Check if this document has a namespace, and if so, try
140     # cross-referencing inside it first.
144     if base_target not in Skipnames:
145         for target in possible_targets:
146             if (target not in Skipfuncs) and not failure_seen(target):
147                 lit_text = nodes.literal(classes=['xref', 'c', 'c-func'])
156                 # work around that by ignoring them.
173                  RE_function: 'c-func',
174                  RE_generic_type: 'c-type',
176                  RE_struct: 'c-struct',
177                  RE_union: 'c-union',
178                  RE_enum: 'c-enum',
179                  RE_typedef: 'c-type',
199     # Check if this document has a namespace, and if so, try
200     # cross-referencing inside it first.
204     if base_target not in Skipnames:
205         for target in possible_targets:
206             if not (match.re == RE_function and target in Skipfuncs):
215                 # work around that by ignoring them.
248     # work around that by ignoring them.
264 # Try to replace a documentation reference for ABI symbols and files
289     # work around that by ignoring them.
314         for l in f:
321     # While we could probably assume that we are running in a git
324     # validity. (Maybe we can do something in the future to warn about
336         # avoid adding cross-references to functions that have been explicitly
355     for para in doctree.traverse(nodes.paragraph):
356         for node in para.traverse(condition=text_but_not_a_reference):
360     app.connect('doctree-resolved', auto_markup)