From 8406d4c1d1d0371c933b6d142b1cd4522c289f83 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 16 Jun 2021 11:58:48 -0400 Subject: Utilities/Sphinx: Index guide section documents for cross-referencing Extend the change from commit 6185265800 (Utilities/Sphinx: Index guide-level documents for cross-referencing, 2019-12-06, v3.17.0-rc1~181^2~1) to name guide documents other than the top level using their docname instead of their title. This will allow them to be cross-referenced by a stable name even if their title changes. --- Utilities/Sphinx/cmake.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index 9fa56cd..9215e14 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -260,6 +260,8 @@ class CMakeTransform(Transform): # Insert the object link target. if objtype == 'command': targetname = title.lower() + elif objtype == 'guide' and not tail.endswith('/index'): + targetname = tail else: if objtype == 'genex': m = CMakeXRefRole._re_genex.match(title) @@ -312,6 +314,7 @@ class CMakeXRefRole(XRefRole): _re = re.compile(r'^(.+?)(\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): # Translate CMake command cross-references of the form: @@ -326,6 +329,10 @@ class CMakeXRefRole(XRefRole): m = CMakeXRefRole._re_genex.match(text) if m: text = '%s <%s>' % (text, m.group(1)) + elif typ == 'cmake:guide': + m = CMakeXRefRole._re_guide.match(text) + if m: + text = '%s <%s>' % (m.group(2), text) # CMake cross-reference targets frequently contain '<' so escape # any explicit `` with '<' not preceded by whitespace. while True: @@ -369,6 +376,10 @@ class CMakeXRefTransform(Transform): continue objname = ref['reftarget'] + if objtype == 'guide' and CMakeXRefRole._re_guide.match(objname): + # Do not index cross-references to guide sections. + continue + targetnum = env.new_serialno('index-%s:%s' % (objtype, objname)) targetid = 'index-%s-%s:%s' % (targetnum, objtype, objname) -- cgit v0.12