The documentation for CPack generators previously lived in their
respective internal CMake modules. This setup was misleading,
because it implied that you should include the modules in your own
code, which is not the case. Moving the documentation into a
separate section does a better job of hiding the internal modules,
which are just an implementation detail. The generator documentation
has also been modified to remove any references to the module name.
The CPackIFW module is a special exception: since it has user-facing
macros, the documentation for these macros has been kept in the module
page, while all other documentation related to the IFW generator has
been moved into the new section.
To make it easier to find the new documentation, the old help pages
for the CPack*.cmake modules have not been deleted, but have been
replaced with a link to their respective help page in the new
documentation section.
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.
Add a document transform to insert index and target nodes just before
any CMake domain cross-reference node. This will make references to
CMake domain objects appear in the index. Also add a comment explaining
why it cannot be done in a result_nodes method of the CMakeXRefRole.
Add identifiers for variables, properties, policies and modules.
This will allow QtCreator to show relevant documentation if it learns
more about the context of the contents of cmake files.
