Browse Source

Utilities/Sphinx: Restore trailing parens on command cross-references

Since commit cc21d0e478 (Utilities/Sphinx: Make signatures linkable,
2023-03-09) we always convert `cmake:command` domain cross-references to
use the explicit `text <text>` form.  This breaks the XRefRole's
`fix_parens` setting that we use to render `cmd` as `cmd()`.
Instead, transform `cmd(sub)` to `cmd(sub) <cmd(sub)>` to preserve
the sub-command link destination, but leave `cmd` alone and let
XRefRole convert it to `cmd()`.
Brad King 2 years ago
parent
commit
c8679f0571
1 changed files with 8 additions and 3 deletions
  1. 8 3
      Utilities/Sphinx/cmake.py

+ 8 - 3
Utilities/Sphinx/cmake.py

@@ -486,14 +486,19 @@ class CMakeXRefRole(XRefRole):
 
     # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'.
     _re = re.compile(r'^(.+?)(\s*)(?<!\x00)<(.*?)>$', re.DOTALL)
-    _re_ref = re.compile(r'^.*\s<\w+([(][\w\s]+[)])?>$', re.DOTALL)
+    _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL)
     _re_genex = re.compile(r'^\$<([^<>:]+)(:[^<>]+)?>$', re.DOTALL)
     _re_guide = re.compile(r'^([^<>/]+)/([^<>]*)$', re.DOTALL)
 
     def __call__(self, typ, rawtext, text, *args, **keys):
         if typ == 'cmake:command':
-            m = CMakeXRefRole._re_ref.match(text)
-            if m is None:
+            # Translate a CMake command cross-reference of the form:
+            #  `command_name(SUB_COMMAND)`
+            # to be its own explicit target:
+            #  `command_name(SUB_COMMAND) <command_name(SUB_COMMAND)>`
+            # so the XRefRole `fix_parens` option does not add more `()`.
+            m = CMakeXRefRole._re_sub.match(text)
+            if m:
                 text = f'{text} <{text}>'
         elif typ == 'cmake:genex':
             m = CMakeXRefRole._re_genex.match(text)