From 2e37a20f027aaf6dd098b58fcb3147706782c1fa Mon Sep 17 00:00:00 2001
From: Matthew Woehlke <matthew.woehlke@kitware.com>
Date: Mon, 13 Mar 2023 15:44:12 -0400
Subject: Utilities/Sphinx: Allow explicit target for genex

Split the genex directive into its own class, allowing a slight
simplification of CMakeObject. Add ability to specify an explicit target
name for the same.

Use this to provide a target for the `$<TARGET_PROPERTY:prop>` generator
expression which is otherwise missing one (due to overlap with
`$<TARGET_PROPERTY:tgt,prop>`).  With this one can write:

    :genex:`$<TARGET_PROPERTY:prop> <TARGET_PROPERTY:prop>`

to link the second variant.

Fixes: #24573
---
 Utilities/Sphinx/cmake.py | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

(limited to 'Utilities')

diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index a07b6e9091..edfbc7b0b5 100644
--- a/Utilities/Sphinx/cmake.py
+++ b/Utilities/Sphinx/cmake.py
@@ -286,19 +286,20 @@ class CMakeTransform(Transform):
             domain.note_object(objtype, targetname, targetid, targetid)
 
 class CMakeObject(ObjectDescription):
+    def __init__(self, *args, **kwargs):
+        self.targetname = None
+        super().__init__(*args, **kwargs)
 
     def handle_signature(self, sig, signode):
         # called from sphinx.directives.ObjectDescription.run()
         signode += addnodes.desc_name(sig, sig)
-        if self.objtype == 'genex':
-            m = CMakeXRefRole._re_genex.match(sig)
-            if m:
-                sig = m.group(1)
         return sig
 
     def add_target_and_index(self, name, sig, signode):
         if self.objtype == 'command':
             targetname = name.lower()
+        elif self.targetname:
+            targetname = self.targetname
         else:
             targetname = name
         targetid = '%s:%s' % (self.objtype, targetname)
@@ -316,6 +317,29 @@ class CMakeObject(ObjectDescription):
         if make_index_entry:
             self.indexnode['entries'].append(make_index_entry(name, targetid))
 
+
+class CMakeGenexObject(CMakeObject):
+    option_spec = {
+        'target': directives.unchanged,
+    }
+
+    def handle_signature(self, sig, signode):
+        name = super().handle_signature(sig, signode)
+
+        m = CMakeXRefRole._re_genex.match(sig)
+        if m:
+            name = m.group(1)
+
+        return name
+
+    def run(self):
+        target = self.options.get('target')
+        if target is not None:
+            self.targetname = target
+
+        return super().run()
+
+
 class CMakeSignatureObject(CMakeObject):
     object_type = 'signature'
 
@@ -507,7 +531,7 @@ class CMakeDomain(Domain):
     directives = {
         'command':    CMakeObject,
         'envvar':     CMakeObject,
-        'genex':      CMakeObject,
+        'genex':      CMakeGenexObject,
         'signature':  CMakeSignatureObject,
         'variable':   CMakeObject,
         # Other `object_types` cannot be created except by the `CMakeTransform`
-- 
cgit v1.2.1