[RFC,2/2] docs: automarkup: Cross-reference CONFIG_ symbols

Commit Message

Nícolas F. R. A. Prado April 4, 2025, 2:02 p.m. UTC

Now that Kconfig symbols are part of the Documentation and have sections
that can be referenced, extend automarkup to automatically
cross-reference CONFIG_ strings to those sections.

Signed-off-by: Nícolas F. R. A. Prado <[e-mail]>
---
 Documentation/sphinx/automarkup.py | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

Patch

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index ecf54d22e9dc6ab459a91fde580c1cf161f054ed..dd940baca480634180a58c209aaed0cd1a16319a 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -47,6 +47,8 @@  RE_abi_symbol = re.compile(r'(\b/(sys|config|proc)/[\w\-/]+)')
 
 RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
 
+RE_kconfig = re.compile(r'CONFIG_[A-Za-z0-9_]+')
+
 #
 # Reserved C words that we should skip when cross-referencing
 #
@@ -88,7 +90,8 @@  def markup_refs(docname, app, node):
                            RE_union: markup_c_ref,
                            RE_enum: markup_c_ref,
                            RE_typedef: markup_c_ref,
-                           RE_git: markup_git}
+                           RE_git: markup_git,
+                           RE_kconfig: markup_kconfig_ref}
 
     match_iterators = [regex.finditer(t) for regex in markup_func]
     #
@@ -260,6 +263,37 @@  def markup_doc_ref(docname, app, match):
     else:
         return nodes.Text(match.group(0))
 
+#
+# Try to replace a kernel config reference of the form CONFIG_... with a
+# cross reference to that kconfig's section
+#
+def markup_kconfig_ref(docname, app, match):
+    stddom = app.env.domains['std']
+    #
+    # Go through the dance of getting an xref out of the std domain
+    #
+    target = match.group(0).lower()
+    xref = None
+    pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'ref',
+                                  reftarget = target, modname = None,
+                                  classname = None, refexplicit = False)
+    #
+    # XXX The Latex builder will throw NoUri exceptions here,
+    # work around that by ignoring them.
+    #
+    try:
+        xref = stddom.resolve_xref(app.env, docname, app.builder, 'ref',
+                                   target, pxref, None)
+    except NoUri:
+        xref = None
+    #
+    # Return the xref if we got it; otherwise just return the plain text.
+    #
+    if xref:
+        return xref
+    else:
+        return nodes.Text(match.group(0))
+
 #
 # Try to replace a documentation reference for ABI symbols and files
 # with a cross reference to that page