Merge topic 'doc-xref-envvar'

63e0c16e3d Help: Link from CMAKE_<LANG>_FLAGS to <LANG>FLAGS environment variables
8acf46caf1 Utilities/Sphinx: Add role and directive for 'envvar' in CMake domain
7e532abc78 Utilities/Sphinx: Fix QtHelp generator identifiers

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Robert Maynard <robert.maynard@kitware.com>
Merge-request: !1985

Help/variable/CMAKE_LANG_FLAGS.rst

@@ -4,3 +4,14 @@ CMAKE_<LANG>_FLAGS
 Flags for all build types.
 
 ``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`.
+
+This is initialized for each language from environment variables:
+
+* ``CMAKE_C_FLAGS``:
+  Initialized by the :envvar:`CFLAGS` environment variable.
+* ``CMAKE_CXX_FLAGS``:
+  Initialized by the :envvar:`CXXFLAGS` environment variable.
+* ``CMAKE_CUDA_FLAGS``:
+  Initialized by the :envvar:`CUDAFLAGS` environment variable.
+* ``CMAKE_Fortran_FLAGS``:
+  Initialized by the :envvar:`FFLAGS` environment variable.

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(),

Utilities/Sphinx/create_identifiers.py

@@ -21,7 +21,9 @@ newlines = []
 for line in lines:
 
   mapping = (("command", "command"),
+             ("envvar", "envvar"),
              ("variable", "variable"),
+             ("generator", "generator"),
              ("target property", "prop_tgt"),
              ("test property", "prop_test"),
              ("source file property", "prop_sf"),