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.
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 @@
_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 @@
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 @@
}
directives = {
'command': CMakeObject,
+ 'envvar': CMakeObject,
'variable': CMakeObject,
# Other object types cannot be created except by the CMakeTransform
# 'generator': CMakeObject,
@@ -355,6 +358,7 @@
}
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 @@
for line in lines:
mapping = (("command", "command"),
+ ("envvar", "envvar"),
("variable", "variable"),
("generator", "generator"),
("target property", "prop_tgt"),
