Utilities/Sphinx: Add role and directive for 'envvar' in CMake domain

This enables cross-reference syntax for CMake environment variables:

    :envvar:`SOMEVAR`

and definition of CMake environment variables via a directive:

    .. envvar:: SOMEVAR

It also adds environment variables defined by the directive and by
`Help/envvar/SOMEVAR.rst` documents to the index.

This `envvar` role and directive is defined in our `cmake` domain
and overrides the equivalent `envvar` role and directive provided
by Sphinx in its default domain.  This is okay because we build
CMake documents in the `cmakd` domain.

This follows up the work from commit v3.10.0-rc1~43^2 (Help: Document
CMake's environment variables, 2017-09-01) that originally added
`envvar` documentation.

2 files changed, 5 insertions, 0 deletions

diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index cfda2d4..90ddd36 100644
--- a/Utilities/Sphinx/cmake.py
+++ b/Utilities/Sphinx/cmake.py
@@ -144,6 +144,7 @@ class _cmake_index_entry:
 
 _cmake_index_objs = {
     'command':    _cmake_index_entry('command'),
+    'envvar':     _cmake_index_entry('envvar'),
     'generator':  _cmake_index_entry('generator'),
     'manual':     _cmake_index_entry('manual'),
     'module':     _cmake_index_entry('module'),
@@ -324,6 +325,7 @@ class CMakeDomain(Domain):
     label = 'CMake'
     object_types = {
         'command':    ObjType('command',    'command'),
+        'envvar':     ObjType('envvar',     'envvar'),
         'generator':  ObjType('generator',  'generator'),
         'variable':   ObjType('variable',   'variable'),
         'module':     ObjType('module',     'module'),
@@ -339,6 +341,7 @@ class CMakeDomain(Domain):
     }
     directives = {
         'command':    CMakeObject,
+        'envvar':     CMakeObject,
         'variable':   CMakeObject,
         # Other object types cannot be created except by the CMakeTransform
         # 'generator':  CMakeObject,
@@ -355,6 +358,7 @@ class CMakeDomain(Domain):
     }
     roles = {
         'command':    CMakeXRefRole(fix_parens = True, lowercase = True),
+        'envvar':     CMakeXRefRole(),
         'generator':  CMakeXRefRole(),
         'variable':   CMakeXRefRole(),
         'module':     CMakeXRefRole(),
diff --git a/Utilities/Sphinx/create_identifiers.py b/Utilities/Sphinx/create_identifiers.py
index 4513434..e638950 100755
--- a/Utilities/Sphinx/create_identifiers.py
+++ b/Utilities/Sphinx/create_identifiers.py
@@ -21,6 +21,7 @@ newlines = []
 for line in lines:
 
   mapping = (("command", "command"),
+             ("envvar", "envvar"),
              ("variable", "variable"),
              ("generator", "generator"),
              ("target property", "prop_tgt"),