Merge topic 'doc-genex'

c2dc7e0f53 Help: Convert genex documentation to sphinx domain objects
778321beb4 Help: Remove extra blank line from cmake-generator-expressions(7)
7d498d6b43 Utilities/Sphinx: Add role and directive for 'genex' in CMake domain
cc1f53351c Help/dev: Mention 'cpack_gen' domain object in CMake Documentation Guide
954a9e9893 Help/dev: Mention 'envvar' domain object in CMake Documentation Guide
621ba5e1f2 cmRST: Add support for 'envvar' directive

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5715

7 files changed, 377 insertions, 109 deletions

diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index c302790..29fc880 100644
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@@ -123,10 +123,23 @@ documentation:
 ``command``
  A CMake language command.
 
+``cpack_gen``
+ A CPack package generator.
+ See the `cpack(1)`_ command-line tool's ``-G`` option.
+
+``envvar``
+ An environment variable.
+ See the `cmake-env-variables(7)`_ manual
+ and the `set()`_ command.
+
 ``generator``
  A CMake native build system generator.
  See the `cmake(1)`_ command-line tool's ``-G`` option.
 
+``genex``
+ A CMake generator expression.
+ See the `cmake-generator-expressions(7)`_ manual.
+
 ``manual``
  A CMake manual page, like the `cmake(1)`_ manual.
 
@@ -160,10 +173,12 @@ which is expected to be of the form::
  -------------
 
 and to appear at or near the top of the ``.rst`` file before any other
-lines starting in a letter, digit, or ``<``.  If no such title appears
+lines starting in a letter, digit, ``<``, or ``$``.  If no such title appears
 literally in the ``.rst`` file, the object name is the ``<file-name>``.
 If a title does appear, it is expected that ``<file-name>`` is equal
-to ``<object-name>`` with any ``<`` and ``>`` characters removed.
+to ``<object-name>`` with any ``<`` and ``>`` characters removed,
+or in the case of a ``$<genex-name>`` or ``$<genex-name:...>``, the
+``genex-name``.
 
 Second, the CMake Domain provides directives to define objects inside
 other documents:
@@ -174,6 +189,14 @@ other documents:
 
   This indented block documents <command-name>.
 
+ .. envvar:: <envvar-name>
+
+  This indented block documents <envvar-name>.
+
+ .. genex:: <genex-name>
+
+  This indented block documents <genex-name>.
+
  .. variable:: <variable-name>
 
   This indented block documents <variable-name>.
@@ -183,11 +206,14 @@ the first approach above.
 
 .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
 .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html
+.. _`cmake-env-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html
+.. _`cmake-generator-expressions(7)`: https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html
 .. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html
 .. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html
 .. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html
 .. _`cmake-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html
 .. _`cmake_policy()`: https://cmake.org/cmake/help/latest/command/cmake_policy.html
+.. _`cpack(1)`: https://cmake.org/cmake/help/latest/manual/cpack.1.html
 .. _`include()`: https://cmake.org/cmake/help/latest/command/include.html
 .. _`set()`: https://cmake.org/cmake/help/latest/command/set.html
 .. _`set_property()`: https://cmake.org/cmake/help/latest/command/set_property.html
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index c949ce1..ca4ea3e 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -46,7 +46,8 @@ Available boolean expressions are:
 Logical Operators
 -----------------
 
-``$<BOOL:string>``
+.. genex:: $<BOOL:string>
+
   Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the
   following is true:
 
@@ -57,23 +58,27 @@ Logical Operators
 
   Otherwise evaluates to ``1``.
 
-``$<AND:conditions>``
+.. genex:: $<AND:conditions>
+
   where ``conditions`` is a comma-separated list of boolean expressions.
   Evaluates to ``1`` if all conditions are ``1``.
   Otherwise evaluates to ``0``.
 
-``$<OR:conditions>``
+.. genex:: $<OR:conditions>
+
   where ``conditions`` is a comma-separated list of boolean expressions.
   Evaluates to ``1`` if at least one of the conditions is ``1``.
   Otherwise evaluates to ``0``.
 
-``$<NOT:condition>``
+.. genex:: $<NOT:condition>
+
   ``0`` if ``condition`` is ``1``, else ``1``.
 
 String Comparisons
 ------------------
 
-``$<STREQUAL:string1,string2>``
+.. genex:: $<STREQUAL:string1,string2>
+
   ``1`` if ``string1`` and ``string2`` are equal, else ``0``.
   The comparison is case-sensitive.  For a case-insensitive comparison,
   combine with a :ref:`string transforming generator expression
@@ -83,101 +88,150 @@ String Comparisons
 
     $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...
 
-``$<EQUAL:value1,value2>``
+.. genex:: $<EQUAL:value1,value2>
+
   ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``.
-``$<IN_LIST:string,list>``
+
+.. genex:: $<IN_LIST:string,list>
+
   ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``.
   Uses case-sensitive comparisons.
-``$<VERSION_LESS:v1,v2>``
+
+.. genex:: $<VERSION_LESS:v1,v2>
+
   ``1`` if ``v1`` is a version less than ``v2``, else ``0``.
-``$<VERSION_GREATER:v1,v2>``
+
+.. genex:: $<VERSION_GREATER:v1,v2>
+
   ``1`` if ``v1`` is a version greater than ``v2``, else ``0``.
-``$<VERSION_EQUAL:v1,v2>``
+
+.. genex:: $<VERSION_EQUAL:v1,v2>
+
   ``1`` if ``v1`` is the same version as ``v2``, else ``0``.
-``$<VERSION_LESS_EQUAL:v1,v2>``
+
+.. genex:: $<VERSION_LESS_EQUAL:v1,v2>
+
   ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``.
-``$<VERSION_GREATER_EQUAL:v1,v2>``
-  ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``.
 
+.. genex:: $<VERSION_GREATER_EQUAL:v1,v2>
+
+  ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``.
 
 Variable Queries
 ----------------
 
-``$<TARGET_EXISTS:target>``
+.. genex:: $<TARGET_EXISTS:target>
+
   ``1`` if ``target`` exists, else ``0``.
-``$<CONFIG:cfgs>``
+
+.. genex:: $<CONFIG:cfgs>
+
   ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a
   case-insensitive comparison. The mapping in
   :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this
   expression when it is evaluated on a property on an :prop_tgt:`IMPORTED`
   target.
-``$<PLATFORM_ID:platform_ids>``
+
+.. genex:: $<PLATFORM_ID:platform_ids>
+
   where ``platform_ids`` is a comma-separated list.
   ``1`` if the CMake's platform id matches any one of the entries in
   ``platform_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_SYSTEM_NAME` variable.
-``$<C_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<C_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the C compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<CXX_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<CXX_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the CXX compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<CUDA_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<CUDA_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the CUDA compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<OBJC_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<OBJC_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the Objective-C compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<OBJCXX_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<OBJCXX_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<Fortran_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<Fortran_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the Fortran compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<ISPC_COMPILER_ID:compiler_ids>``
+
+.. genex:: $<ISPC_COMPILER_ID:compiler_ids>
+
   where ``compiler_ids`` is a comma-separated list.
   ``1`` if the CMake's compiler id of the ISPC compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<C_COMPILER_VERSION:version>``
+
+.. genex:: $<C_COMPILER_VERSION:version>
+
   ``1`` if the version of the C compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<CXX_COMPILER_VERSION:version>``
+
+.. genex:: $<CXX_COMPILER_VERSION:version>
+
   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<CUDA_COMPILER_VERSION:version>``
+
+.. genex:: $<CUDA_COMPILER_VERSION:version>
+
   ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<OBJC_COMPILER_VERSION:version>``
+
+.. genex:: $<OBJC_COMPILER_VERSION:version>
+
   ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<OBJCXX_COMPILER_VERSION:version>``
+
+.. genex:: $<OBJCXX_COMPILER_VERSION:version>
+
   ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<Fortran_COMPILER_VERSION:version>``
+
+.. genex:: $<Fortran_COMPILER_VERSION:version>
+
   ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<ISPC_COMPILER_VERSION:version>``
+
+.. genex:: $<ISPC_COMPILER_VERSION:version>
+
   ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<TARGET_POLICY:policy>``
+
+.. genex:: $<TARGET_POLICY:policy>
+
   ``1`` if the ``policy`` was NEW when the 'head' target was created,
   else ``0``.  If the ``policy`` was not set, the warning message for the policy
   will be emitted. This generator expression only works for a subset of
   policies.
-``$<COMPILE_FEATURES:features>``
+
+.. genex:: $<COMPILE_FEATURES:features>
+
   where ``features`` is a comma-spearated list.
   Evaluates to ``1`` if all of the ``features`` are available for the 'head'
   target, and ``0`` otherwise. If this expression is used while evaluating
@@ -189,7 +243,8 @@ Variable Queries
 
 .. _`Boolean COMPILE_LANGUAGE Generator Expression`:
 
-``$<COMPILE_LANG_AND_ID:language,compiler_ids>``
+.. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids>
+
   ``1`` when the language used for compilation unit matches ``language`` and
   the CMake's compiler id of the language compiler matches any one of the
   entries in ``compiler_ids``, otherwise ``0``. This expression is a short form
@@ -225,7 +280,8 @@ Variable Queries
               $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
     )
 
-``$<COMPILE_LANGUAGE:languages>``
+.. genex:: $<COMPILE_LANGUAGE:languages>
+
   ``1`` when the language used for compilation unit matches any of the entries
   in ``languages``, otherwise ``0``.  This expression may be used to specify
   compile options, compile definitions, and include directories for source files of a
@@ -270,7 +326,8 @@ Variable Queries
 
 .. _`Boolean LINK_LANGUAGE Generator Expression`:
 
-``$<LINK_LANG_AND_ID:language,compiler_ids>``
+.. genex:: $<LINK_LANG_AND_ID:language,compiler_ids>
+
   ``1`` when the language used for link step matches ``language`` and the
   CMake's compiler id of the language linker matches any one of the entries
   in ``compiler_ids``, otherwise ``0``. This expression is a short form for the
@@ -309,7 +366,8 @@ Variable Queries
   ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
   generator expression.
 
-``$<LINK_LANGUAGE:languages>``
+.. genex:: $<LINK_LANGUAGE:languages>
+
   ``1`` when the language used for link step matches any of the entries
   in ``languages``, otherwise ``0``.  This expression may be used to specify
   link libraries, link options, link directories and link dependencies of a
@@ -371,14 +429,16 @@ Variable Queries
     evaluation will give ``C`` as link language, so the second pass will
     correctly add target ``libother`` as link dependency.
 
-``$<DEVICE_LINK:list>``
+.. genex:: $<DEVICE_LINK:list>
+
   Returns the list if it is the device link step, an empty list otherwise.
   The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
   and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and
   policy :policy:`CMP0105`. This expression can only be used to specify link
   options.
 
-``$<HOST_LINK:list>``
+.. genex:: $<HOST_LINK:list>
+
   Returns the list if it is the normal link step, an empty list otherwise.
   This expression is mainly useful when a device link step is also involved
   (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only
@@ -434,11 +494,16 @@ Escaped Characters
 
 String literals to escape the special meaning a character would otherwise have:
 
-``$<ANGLE-R>``
+.. genex:: $<ANGLE-R>
+
   A literal ``>``. Used for example to compare strings that contain a ``>``.
-``$<COMMA>``
+
+.. genex:: $<COMMA>
+
   A literal ``,``. Used for example to compare strings which contain a ``,``.
-``$<SEMICOLON>``
+
+.. genex:: $<SEMICOLON>
+
   A literal ``;``. Used to prevent list expansion on an argument with ``;``.
 
 .. _`Conditional Generator Expressions`:
@@ -449,11 +514,13 @@ Conditional Expressions
 Conditional generator expressions depend on a boolean condition
 that must be ``0`` or ``1``.
 
-``$<condition:true_string>``
+.. genex:: $<condition:true_string>
+
   Evaluates to ``true_string`` if ``condition`` is ``1``.
   Otherwise evaluates to the empty string.
 
-``$<IF:condition,true_string,false_string>``
+.. genex:: $<IF:condition,true_string,false_string>
+
   Evaluates to ``true_string`` if ``condition`` is ``1``.
   Otherwise evaluates to ``false_string``.
 
@@ -472,22 +539,34 @@ otherwise expands to the empty string.
 String Transformations
 ----------------------
 
-``$<JOIN:list,string>``
+.. genex:: $<JOIN:list,string>
+
   Joins the list with the content of ``string``.
-``$<REMOVE_DUPLICATES:list>``
+
+.. genex:: $<REMOVE_DUPLICATES:list>
+
   Removes duplicated items in the given ``list``.
-``$<FILTER:list,INCLUDE|EXCLUDE,regex>``
+
+.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex>
+
   Includes or removes items from ``list`` that match the regular expression ``regex``.
-``$<LOWER_CASE:string>``
+
+.. genex:: $<LOWER_CASE:string>
+
   Content of ``string`` converted to lower case.
-``$<UPPER_CASE:string>``
+
+.. genex:: $<UPPER_CASE:string>
+
   Content of ``string`` converted to upper case.
 
-``$<GENEX_EVAL:expr>``
+.. genex:: $<GENEX_EVAL:expr>
+
   Content of ``expr`` evaluated as a generator expression in the current
   context. This enables consumption of generator expressions whose
   evaluation results itself in generator expressions.
-``$<TARGET_GENEX_EVAL:tgt,expr>``
+
+.. genex:: $<TARGET_GENEX_EVAL:tgt,expr>
+
   Content of ``expr`` evaluated as a generator expression in the context of
   ``tgt`` target. This enables consumption of custom target properties that
   themselves contain generator expressions.
@@ -526,62 +605,99 @@ String Transformations
 Variable Queries
 ----------------
 
-``$<CONFIG>``
+.. genex:: $<CONFIG>
+
   Configuration name.
-``$<CONFIGURATION>``
+
+.. genex:: $<CONFIGURATION>
+
   Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead.
-``$<PLATFORM_ID>``
+
+.. genex:: $<PLATFORM_ID>
+
   The current system's CMake platform id.
   See also the :variable:`CMAKE_SYSTEM_NAME` variable.
-``$<C_COMPILER_ID>``
+
+.. genex:: $<C_COMPILER_ID>
+
   The CMake's compiler id of the C compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<CXX_COMPILER_ID>``
+
+.. genex:: $<CXX_COMPILER_ID>
+
   The CMake's compiler id of the CXX compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<CUDA_COMPILER_ID>``
+
+.. genex:: $<CUDA_COMPILER_ID>
+
   The CMake's compiler id of the CUDA compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<OBJC_COMPILER_ID>``
+
+.. genex:: $<OBJC_COMPILER_ID>
+
   The CMake's compiler id of the OBJC compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<OBJCXX_COMPILER_ID>``
+
+.. genex:: $<OBJCXX_COMPILER_ID>
+
   The CMake's compiler id of the OBJCXX compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<Fortran_COMPILER_ID>``
+
+.. genex:: $<Fortran_COMPILER_ID>
+
   The CMake's compiler id of the Fortran compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<ISPC_COMPILER_ID>``
+
+.. genex:: $<ISPC_COMPILER_ID>
+
   The CMake's compiler id of the ISPC compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
-``$<C_COMPILER_VERSION>``
+
+.. genex:: $<C_COMPILER_VERSION>
+
   The version of the C compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<CXX_COMPILER_VERSION>``
+
+.. genex:: $<CXX_COMPILER_VERSION>
+
   The version of the CXX compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<CUDA_COMPILER_VERSION>``
+
+.. genex:: $<CUDA_COMPILER_VERSION>
+
   The version of the CUDA compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<OBJC_COMPILER_VERSION>``
+
+.. genex:: $<OBJC_COMPILER_VERSION>
+
   The version of the OBJC compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<OBJCXX_COMPILER_VERSION>``
+
+.. genex:: $<OBJCXX_COMPILER_VERSION>
+
   The version of the OBJCXX compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<Fortran_COMPILER_VERSION>``
+
+.. genex:: $<Fortran_COMPILER_VERSION>
+
   The version of the Fortran compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<ISPC_COMPILER_VERSION>``
+
+.. genex:: $<ISPC_COMPILER_VERSION>
+
   The version of the ISPC compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
-``$<COMPILE_LANGUAGE>``
+
+.. genex:: $<COMPILE_LANGUAGE>
+
   The compile language of source files when evaluating compile options.
   See :ref:`the related boolean expression
   <Boolean COMPILE_LANGUAGE Generator Expression>`
   ``$<COMPILE_LANGUAGE:language>``
   for notes about the portability of this generator expression.
-``$<LINK_LANGUAGE>``
+
+.. genex:: $<LINK_LANGUAGE>
+
   The link language of target when evaluating link options.
   See :ref:`the related boolean expression
   <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>``
@@ -608,14 +724,19 @@ In the following, "the ``tgt`` filename" means the name of the ``tgt``
 binary file. This has to be distinguished from "the target name",
 which is just the string ``tgt``.
 
-``$<TARGET_NAME_IF_EXISTS:tgt>``
+.. genex:: $<TARGET_NAME_IF_EXISTS:tgt>
+
   The target name ``tgt`` if the target exists, an empty string otherwise.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_FILE:tgt>``
+
+.. genex:: $<TARGET_FILE:tgt>
+
   Full path to the ``tgt`` binary file.
-``$<TARGET_FILE_BASE_NAME:tgt>``
+
+.. genex:: $<TARGET_FILE_BASE_NAME:tgt>
+
   Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and
   suffix.
   For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``.
@@ -632,36 +753,48 @@ which is just the string ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_FILE_PREFIX:tgt>``
+
+.. genex:: $<TARGET_FILE_PREFIX:tgt>
+
   Prefix of the ``tgt`` filename (such as ``lib``).
 
   See also the :prop_tgt:`PREFIX` target property.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_FILE_SUFFIX:tgt>``
+
+.. genex:: $<TARGET_FILE_SUFFIX:tgt>
+
   Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``).
 
   See also the :prop_tgt:`SUFFIX` target property.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_FILE_NAME:tgt>``
+
+.. genex:: $<TARGET_FILE_NAME:tgt>
+
   The ``tgt`` filename.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_FILE_DIR:tgt>``
+
+.. genex:: $<TARGET_FILE_DIR:tgt>
+
   Directory of the ``tgt`` binary file.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_LINKER_FILE:tgt>``
+
+.. genex:: $<TARGET_LINKER_FILE:tgt>
+
   File used when linking to the ``tgt`` target.  This will usually
   be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``),
   but for a shared library on DLL platforms, it would be the ``.lib``
   import library associated with the DLL.
-``$<TARGET_LINKER_FILE_BASE_NAME:tgt>``
+
+.. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt>
+
   Base name of file used to link the target ``tgt``, i.e.
   ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example,
   if target file name is ``libbase.a``, the base name is ``base``.
@@ -677,7 +810,9 @@ which is just the string ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_LINKER_FILE_PREFIX:tgt>``
+
+.. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt>
+
   Prefix of file used to link target ``tgt``.
 
   See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target
@@ -685,7 +820,9 @@ which is just the string ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_LINKER_FILE_SUFFIX:tgt>``
+
+.. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt>
+
   Suffix of file used to link where ``tgt`` is the name of a target.
 
   The suffix corresponds to the file extension (such as ".so" or ".lib").
@@ -695,36 +832,49 @@ which is just the string ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_LINKER_FILE_NAME:tgt>``
+
+.. genex:: $<TARGET_LINKER_FILE_NAME:tgt>
+
   Name of file used to link target ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_LINKER_FILE_DIR:tgt>``
+
+.. genex:: $<TARGET_LINKER_FILE_DIR:tgt>
+
   Directory of file used to link target ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_SONAME_FILE:tgt>``
+
+.. genex:: $<TARGET_SONAME_FILE:tgt>
+
   File with soname (``.so.3``) where ``tgt`` is the name of a target.
-``$<TARGET_SONAME_FILE_NAME:tgt>``
+.. genex:: $<TARGET_SONAME_FILE_NAME:tgt>
+
   Name of file with soname (``.so.3``).
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_SONAME_FILE_DIR:tgt>``
+
+.. genex:: $<TARGET_SONAME_FILE_DIR:tgt>
+
   Directory of with soname (``.so.3``).
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_PDB_FILE:tgt>``
+
+.. genex:: $<TARGET_PDB_FILE:tgt>
+
   Full path to the linker generated program database file (.pdb)
   where ``tgt`` is the name of a target.
 
   See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
   target properties and their configuration specific variants
   :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`.
-``$<TARGET_PDB_FILE_BASE_NAME:tgt>``
+
+.. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt>
+
   Base name of the linker generated program database file (.pdb)
   where ``tgt`` is the name of a target.
 
@@ -740,23 +890,31 @@ which is just the string ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_PDB_FILE_NAME:tgt>``
+
+.. genex:: $<TARGET_PDB_FILE_NAME:tgt>
+
   Name of the linker generated program database file (.pdb).
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_PDB_FILE_DIR:tgt>``
+
+.. genex:: $<TARGET_PDB_FILE_DIR:tgt>
+
   Directory of the linker generated program database file (.pdb).
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_BUNDLE_DIR:tgt>``
+
+.. genex:: $<TARGET_BUNDLE_DIR:tgt>
+
   Full path to the bundle directory (``my.app``, ``my.framework``, or
   ``my.bundle``) where ``tgt`` is the name of a target.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_BUNDLE_CONTENT_DIR:tgt>``
+
+.. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt>
+
   Full path to the bundle content directory where ``tgt`` is the name of a
   target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``,
   or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to
@@ -765,17 +923,23 @@ which is just the string ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on (see policy :policy:`CMP0112`).
-``$<TARGET_PROPERTY:tgt,prop>``
+
+.. genex:: $<TARGET_PROPERTY:tgt,prop>
+
   Value of the property ``prop`` on the target ``tgt``.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
-``$<TARGET_PROPERTY:prop>``
+
+.. genex:: $<TARGET_PROPERTY:prop>
+
   Value of the property ``prop`` on the target for which the expression
   is being evaluated. Note that for generator expressions in
   :ref:`Target Usage Requirements` this is the consuming target rather
   than the target specifying the requirement.
-``$<INSTALL_PREFIX>``
+
+.. genex:: $<INSTALL_PREFIX>
+
   Content of the install prefix when the target is exported via
   :command:`install(EXPORT)`, or when evaluated in
   :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise.
@@ -783,30 +947,43 @@ which is just the string ``tgt``.
 Output-Related Expressions
 --------------------------
 
-``$<TARGET_NAME:...>``
+.. genex:: $<TARGET_NAME:...>
+
   Marks ``...`` as being the name of a target.  This is required if exporting
   targets to multiple dependent export sets.  The ``...`` must be a literal
   name of a target- it may not contain generator expressions.
-``$<LINK_ONLY:...>``
+
+.. genex:: $<LINK_ONLY:...>
+
   Content of ``...`` except when evaluated in a link interface while
   propagating :ref:`Target Usage Requirements`, in which case it is the
   empty string.
   Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
   property, perhaps via the :command:`target_link_libraries` command,
   to specify private link dependencies without other usage requirements.
-``$<INSTALL_INTERFACE:...>``
+
+.. genex:: $<INSTALL_INTERFACE:...>
+
   Content of ``...`` when the property is exported using :command:`install(EXPORT)`,
   and empty otherwise.
-``$<BUILD_INTERFACE:...>``
+
+.. genex:: $<BUILD_INTERFACE:...>
+
   Content of ``...`` when the property is exported using :command:`export`, or
   when the target is used by another target in the same buildsystem. Expands to
   the empty string otherwise.
-``$<MAKE_C_IDENTIFIER:...>``
+
+.. genex:: $<MAKE_C_IDENTIFIER:...>
+
   Content of ``...`` converted to a C identifier.  The conversion follows the
   same behavior as :command:`string(MAKE_C_IDENTIFIER)`.
-``$<TARGET_OBJECTS:objLib>``
+
+.. genex:: $<TARGET_OBJECTS:objLib>
+
   List of objects resulting from build of ``objLib``.
-``$<SHELL_PATH:...>``
+
+.. genex:: $<SHELL_PATH:...>
+
   Content of ``...`` converted to shell path style. For example, slashes are
   converted to backslashes in Windows shells and drive letters are converted
   to posix paths in MSYS shells. The ``...`` must be an absolute path.
@@ -816,7 +993,8 @@ Output-Related Expressions
   ``;`` on Windows).  Be sure to enclose the argument containing this genex
   in double quotes in CMake source code so that ``;`` does not split arguments.
 
-``$<OUTPUT_CONFIG:...>``
+.. genex:: $<OUTPUT_CONFIG:...>
+
   .. versionadded:: 3.20
 
   Only valid in :command:`add_custom_command` and :command:`add_custom_target`
@@ -825,7 +1003,8 @@ Output-Related Expressions
   in ``...`` are evaluated using the custom command's "output config".
   With other generators, the content of ``...`` is evaluated normally.
 
-``$<COMMAND_CONFIG:...>``
+.. genex:: $<COMMAND_CONFIG:...>
+
   .. versionadded:: 3.20
 
   Only valid in :command:`add_custom_command` and :command:`add_custom_target`
diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx
index 26e93bb..fce6e80 100644
--- a/Source/cmRST.cxx
+++ b/Source/cmRST.cxx
@@ -25,7 +25,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot)
   , Markup(MarkupNone)
   , Directive(DirectiveNone)
   , CMakeDirective("^.. (cmake:)?("
-                   "command|variable"
+                   "command|envvar|genex|variable"
                    ")::[ \t]+([^ \t\n]+)$")
   , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$")
   , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$")
@@ -37,7 +37,8 @@ cmRST::cmRST(std::ostream& os, std::string docroot)
   , NoteDirective("^.. note::[ \t]*(.*)$")
   , ModuleRST(R"(^#\[(=*)\[\.rst:$)")
   , CMakeRole("(:cmake)?:("
-              "command|cpack_gen|generator|variable|envvar|module|policy|"
+              "command|cpack_gen|generator|genex|"
+              "variable|envvar|module|policy|"
               "prop_cache|prop_dir|prop_gbl|prop_inst|prop_sf|"
               "prop_test|prop_tgt|"
               "manual"
diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect
index 970adaa..4870f65 100644
--- a/Tests/CMakeLib/testRST.expect
+++ b/Tests/CMakeLib/testRST.expect
@@ -20,6 +20,12 @@ Environment variable ``SOME_ENV_VAR``.
 Environment variable ``some env var`` with space and target.
 Generator ``Some Generator`` with space.
 Generator ``Some Generator`` with space.
+Generator expression ``SOME_GENEX``.
+Generator expression ``$<SOME_GENEX>`` with brackets.
+Generator expression ``$<SOME_GENEX:...>`` with brackets and parameter.
+Generator expression ``some genex`` with space and target.
+Generator expression ``$<SOME_GENEX>`` with brackets, space, and target.
+Generator expression ``$<SOME_GENEX:...>`` with brackets, parameter, space, and target.
 Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``.
 Inline link Link Text.
 Inline link Link Text <With \-escaped Brackets>.
@@ -48,6 +54,22 @@ Bracket Comment Content
 
    Command other_cmd description.
 
+.. cmake:envvar:: some_var
+
+   Environment variable some_var description.
+
+.. envvar:: other_var
+
+   Environment variable other_var description.
+
+.. cmake:genex:: SOME_GENEX
+
+   Generator expression SOME_GENEX description.
+
+.. genex:: $<OTHER_GENEX>
+
+   Generator expression $<OTHER_GENEX> description.
+
 .. cmake:variable:: some_var
 
    Variable some_var description.
diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst
index 6462f1b..44931a7 100644
--- a/Tests/CMakeLib/testRST.rst
+++ b/Tests/CMakeLib/testRST.rst
@@ -27,6 +27,12 @@ Environment variable :envvar:`SOME_ENV_VAR`.
 Environment variable :envvar:`some env var <SOME_ENV_VAR>` with space and target.
 Generator :generator:`Some Generator` with space.
 Generator :cpack_gen:`Some Generator` with space.
+Generator expression :genex:`SOME_GENEX`.
+Generator expression :genex:`$<SOME_GENEX>` with brackets.
+Generator expression :genex:`$<SOME_GENEX:...>` with brackets and parameter.
+Generator expression :genex:`some genex <SOME_GENEX>` with space and target.
+Generator expression :genex:`$<SOME_GENEX> <SOME_GENEX>` with brackets, space, and target.
+Generator expression :genex:`$<SOME_GENEX:...> <SOME_GENEX>` with brackets, parameter, space, and target.
 Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``.
 Inline link `Link Text <ExternalDest>`_.
 Inline link `Link Text \<With \\-escaped Brackets\> <ExternalDest>`_.
@@ -51,6 +57,22 @@ Inline literal ``__`` followed by inline link `Link Text <InternalDest_>`_.
 
    Command other_cmd description.
 
+.. cmake:envvar:: some_var
+
+   Environment variable some_var description.
+
+.. envvar:: other_var
+
+   Environment variable other_var description.
+
+.. cmake:genex:: SOME_GENEX
+
+   Generator expression SOME_GENEX description.
+
+.. genex:: $<OTHER_GENEX>
+
+   Generator expression $<OTHER_GENEX> description.
+
 .. cmake:variable:: some_var
 
    Variable some_var description.
diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index e175d0d..ece4bf5 100644
--- a/Utilities/Sphinx/cmake.py
+++ b/Utilities/Sphinx/cmake.py
@@ -191,6 +191,7 @@ _cmake_index_objs = {
     'cpack_gen':  _cmake_index_entry('cpack generator'),
     'envvar':     _cmake_index_entry('envvar'),
     'generator':  _cmake_index_entry('generator'),
+    'genex':      _cmake_index_entry('genex'),
     'guide':      _cmake_index_entry('guide'),
     'manual':     _cmake_index_entry('manual'),
     'module':     _cmake_index_entry('module'),
@@ -224,7 +225,7 @@ class CMakeTransform(Transform):
         self.titles = {}
 
     def parse_title(self, docname):
-        """Parse a document title as the first line starting in [A-Za-z0-9<]
+        """Parse a document title as the first line starting in [A-Za-z0-9<$]
            or fall back to the document basename if no such line exists.
            The cmake --help-*-list commands also depend on this convention.
            Return the title or False if the document file does not exist.
@@ -239,7 +240,7 @@ class CMakeTransform(Transform):
                 title = False
             else:
                 for line in f:
-                    if len(line) > 0 and (line[0].isalnum() or line[0] == '<'):
+                    if len(line) > 0 and (line[0].isalnum() or line[0] == '<' or line[0] == '$'):
                         title = line.rstrip()
                         break
                 f.close()
@@ -260,6 +261,10 @@ class CMakeTransform(Transform):
             if objtype == 'command':
                 targetname = title.lower()
             else:
+                if objtype == 'genex':
+                    m = CMakeXRefRole._re_genex.match(title)
+                    if m:
+                        title = m.group(1)
                 targetname = title
             targetid = '%s:%s' % (objtype, targetname)
             targetnode = nodes.target('', '', ids=[targetid])
@@ -277,6 +282,10 @@ class CMakeObject(ObjectDescription):
     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):
@@ -302,6 +311,7 @@ class CMakeXRefRole(XRefRole):
     # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'.
     _re = re.compile(r'^(.+?)(\s*)(?<!\x00)<(.*?)>$', re.DOTALL)
     _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL)
+    _re_genex = re.compile(r'^\$<([^<>:]+)(:[^<>]+)?>$', re.DOTALL)
 
     def __call__(self, typ, rawtext, text, *args, **keys):
         # Translate CMake command cross-references of the form:
@@ -312,6 +322,10 @@ class CMakeXRefRole(XRefRole):
             m = CMakeXRefRole._re_sub.match(text)
             if m:
                 text = '%s <%s>' % (text, m.group(1))
+        elif typ == 'cmake:genex':
+            m = CMakeXRefRole._re_genex.match(text)
+            if m:
+                text = '%s <%s>' % (text, m.group(1))
         # CMake cross-reference targets frequently contain '<' so escape
         # any explicit `<target>` with '<' not preceded by whitespace.
         while True:
@@ -374,6 +388,7 @@ class CMakeDomain(Domain):
         'cpack_gen':  ObjType('cpack_gen',  'cpack_gen'),
         'envvar':     ObjType('envvar',     'envvar'),
         'generator':  ObjType('generator',  'generator'),
+        'genex':      ObjType('genex',      'genex'),
         'guide':      ObjType('guide',      'guide'),
         'variable':   ObjType('variable',   'variable'),
         'module':     ObjType('module',     'module'),
@@ -390,6 +405,7 @@ class CMakeDomain(Domain):
     directives = {
         'command':    CMakeObject,
         'envvar':     CMakeObject,
+        'genex':      CMakeObject,
         'variable':   CMakeObject,
         # Other object types cannot be created except by the CMakeTransform
         # 'generator':  CMakeObject,
@@ -409,6 +425,7 @@ class CMakeDomain(Domain):
         'cpack_gen':  CMakeXRefRole(),
         'envvar':     CMakeXRefRole(),
         'generator':  CMakeXRefRole(),
+        'genex':      CMakeXRefRole(),
         'guide':      CMakeXRefRole(),
         'variable':   CMakeXRefRole(),
         'module':     CMakeXRefRole(),
diff --git a/Utilities/Sphinx/create_identifiers.py b/Utilities/Sphinx/create_identifiers.py
index e35f127..0ff39a0 100755
--- a/Utilities/Sphinx/create_identifiers.py
+++ b/Utilities/Sphinx/create_identifiers.py
@@ -25,6 +25,7 @@ for line in lines:
              ("envvar", "envvar"),
              ("variable", "variable"),
              ("generator", "generator"),
+             ("genex", "genex"),
              ("guide", "guide"),
              ("target property", "prop_tgt"),
              ("test property", "prop_test"),