docs: sphinx/automarkup: add cross-references for ABI

Now that all ABI files are handled together, we can add a feature
at automarkup for it to generate cross-references for ABI symbols.

The cross-reference logic can produce references for all existing
files, except for README (as this is not parsed).

For symbols, they need to be an exact match of what it is
described at the docs, which is not always true due to wildcards.

If symbols at /sys /proc and /config are identical, a cross-reference
will be used.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org

authored by

Mauro Carvalho Chehab and committed by

Jonathan Corbet 1 year ago c9408169 4bb2dbd7

+56

2 changed files

expand all

Documentation

sphinx

automarkup.py

scripts

lib

abi

abi_parser.py

+45

Documentation/sphinx/automarkup.py

··· 11 11 import re 12 12 from itertools import chain 13 13 14 + from kernel_abi import kernel_abi 15 + 14 16 # 15 17 # Python 2 lacks re.ASCII... 16 18 # ··· 50 48 # an optional extension 51 49 # 52 50 RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)') 51 + RE_abi_file = re.compile(r'(\bDocumentation/ABI/[\w\-/]+)') 52 + RE_abi_symbol = re.compile(r'(\b/(sys|config|proc)/[\w\-/]+)') 53 53 54 54 RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') 55 55 ··· 88 84 # Associate each regex with the function that will markup its matches 89 85 # 90 86 markup_func_sphinx2 = {RE_doc: markup_doc_ref, 87 + RE_abi_file: markup_abi_ref, 88 + RE_abi_symbol: markup_abi_ref, 91 89 RE_function: markup_c_ref, 92 90 RE_generic_type: markup_c_ref} 93 91 94 92 markup_func_sphinx3 = {RE_doc: markup_doc_ref, 93 + RE_abi_file: markup_abi_ref, 94 + RE_abi_symbol: markup_abi_ref, 95 95 RE_function: markup_func_ref_sphinx3, 96 96 RE_struct: markup_c_ref, 97 97 RE_union: markup_c_ref, ··· 267 259 # 268 260 try: 269 261 xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc', 262 + target, pxref, None) 263 + except NoUri: 264 + xref = None 265 + # 266 + # Return the xref if we got it; otherwise just return the plain text. 267 + # 268 + if xref: 269 + return xref 270 + else: 271 + return nodes.Text(match.group(0)) 272 + 273 + # 274 + # Try to replace a documentation reference of the form Documentation/ABI/... 275 + # with a cross reference to that page 276 + # 277 + def markup_abi_ref(docname, app, match): 278 + stddom = app.env.domains['std'] 279 + # 280 + # Go through the dance of getting an xref out of the std domain 281 + # 282 + fname = match.group(1) 283 + target = kernel_abi.xref(fname) 284 + 285 + # Kernel ABI doesn't describe such file or symbol 286 + if not target: 287 + return nodes.Text(match.group(0)) 288 + 289 + pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'ref', 290 + reftarget = target, modname = None, 291 + classname = None, refexplicit = False) 292 + 293 + # 294 + # XXX The Latex builder will throw NoUri exceptions here, 295 + # work around that by ignoring them. 296 + # 297 + try: 298 + xref = stddom.resolve_xref(app.env, docname, app.builder, 'ref', 270 299 target, pxref, None) 271 300 except NoUri: 272 301 xref = None

+11

scripts/lib/abi/abi_parser.py

··· 391 391 392 392 return desc + "\n\n" 393 393 394 + def xref(self, fname): 395 + """ 396 + Converts a Documentation/ABI + basename into a ReST cross-reference 397 + """ 398 + 399 + xref = self.file_refs.get(fname) 400 + if not xref: 401 + return None 402 + else: 403 + return xref 404 + 394 405 def desc_rst(self, desc): 395 406 """Enrich ReST output by creating cross-references""" 396 407

Configure Feed

Configure Feed