Merge topic 'genex-explicit-target'

2e37a20f02 Utilities/Sphinx: Allow explicit target for genex

Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Raul Tambre <raul@tambre.ee>
Merge-request: !8321

3 files changed, 34 insertions, 5 deletions

diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index 8cd71b4..1dd23c6 100644
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@@ -241,6 +241,10 @@ Document a "genex" object:
 
 The directive requires a single argument, the generator expression name.
 
+The optional ``:target:`` option allows a custom target name to be specified.
+Because this will affect the ability to reference the "genex" object using the
+``:genex:`` role, this option should be used very sparingly.
+
 ``signature`` directive
 ^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index a640c13..9da3799 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1418,6 +1418,7 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
     expression is being evaluated.
 
 .. genex:: $<TARGET_PROPERTY:prop>
+  :target: TARGET_PROPERTY:prop
 
   Value of the property ``prop`` on the target for which the expression
   is being evaluated. Note that for generator expressions in
diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index a07b6e9..edfbc7b 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`