Extend the change from commit 6185265800 (Utilities/Sphinx: Index
guide-level documents for cross-referencing, 2019-12-06,
v3.17.0-rc1~181^2~1) to name guide documents other than the top level
using their docname instead of their title. This will allow them to be
cross-referenced by a stable name even if their title changes.
Sphinx 4 by default generates `man/#/foo.#`, but older versions generate
`man/foo.#` as our install rules expect. Update our Sphinx config file
to tell Sphinx 4 to use the old layout.
Fixes: #22192
47ab2d4d2e Help: Clarify role of binaryDir inheritance in cmake-presets(7)
0e3c361f77 Help: Link to tool-specific preset arguments from cmake-presets(7)
dd6165fbd4 Help: Mention version 2 in cmake-presets(7)
cdbd1ae64b Utilities/Sphinx: Avoid converting -- to an en-dash
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5829
This enables cross-reference syntax for CMake generator expressions:
:genex:`SOME_GENEX`
:genex:`$<SOME_GENEX>`
:genex:`$<SOME_GENEX:...>`
and definition of CMake generator expressions via a directive:
.. genex:: SOME_GENEX
.. genex:: $<SOME_GENEX>
.. genex:: $<SOME_GENEX:...>
It also adds generator expressions defined by the directive and by
`Help/genex/SOME_GENEX.rst` documents to the index.
Sphinx has deprecated `sphinx.util.pycompat.htmlescape` and
`sphinx.builders.qthelp.QtHelpBuilder`. We only import these as part of
a monkey-patch to work around a bug in versions of sphinx before 1.7.2,
so make that code path conditional. The imports are not deprecated on
the versions where we need them.
Extend the change from commit d2fde94809 (Help: Add infrastructure for
guide-level documentation, 2019-05-30, v3.16.0-rc1~531^2~4) to add
support for cross-referencing and indexing the guides.
We use the convention `Help/<type>/<doc>` for indexing each document as
an object of type `<type>`. Split the document name on the first slash
rather than the last slash so that multi-level documents like
`Help/guide/tutorial/index.rst` are indexed as their top-level type.
* The code snippets in the docs consist of CMake code mixed
with syntax definition punctuation like < > [ ] ... Therefore
a pure CMake lexer is inadequate. Here it is replaced by a
CMake syntax definition parser.
* Fixed syntax definition snippets in FindPkgConfig.cmake to
make best use of syntax highlighting. This source file is the
hardest to support because it contains comparison operators
<= = >=, which need special attention to avoid confusion
with the placeholder indicators <...>.
* Fixed syntax in execute_process.rst (there were unbalanced
brackets).
* Disabled syntax highlighting for long string examples in
cmake-language.7.rst.
* No highlighting of removed syntax in CMP0049
* To inspect the outcome of this patch, see e.g. the pages
* manual/cmake-buildsystem.7.html
* module/ExternalProject.html
* module/FindPkgConfig.html
which are particularly rich in complex code snippets.
CMake 3.12 introduced a `...<max>` syntax in the version given to
`cmake_minimum_required` to automatically set policies to NEW up
to that version. Use it to avoid listing policies explicitly.
The syntax is compatible with older versions of CMake such that they use
the extended version string for the `CMAKE_MINIMUM_REQUIRED_VERSION`
variable (which we don't use) but otherwise ignore it.
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.
Hyperlink text color does not stand out when used inside a literal block
because such blocks typically get syntax highlighting. Update our CSS
style to make the links more distinct.
Suggested-by: Kyle Edwards <kyle.edwards@kitware.com>
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.
Since commit v3.8.0-rc2~28^2~2 (Utilities/Sphinx: Port cmake extension
to Sphinx 1.4, 2017-02-09) we use the `sphinx.version_info` tuple.
However, it was added in Sphinx v1.2 so the check breaks compatibility
with older versions. Revise our check to assume Sphinx pre-1.2 if the
version tuple does not exist.
