Provide readers following the tutorial on `cmake.org` a direct link to
download the tutorial's source examples. Previously readers had to
fetch the CMake source tree separately and look for the tutorial source
examples inside it.
Fixes: #22475
2808281730 gitlab-ci: update cmake.org documentation in release package pipeline
ed00a29cce gitlab-ci: consolidate jobs for cmake.org/cmake/help/git-{master,stage} docs
5c2e8ce515 Utilities/Sphinx: Add OpenSearch link to html page headers on cmake.org
a14905d4df Utilities/Sphinx: Add option to build outdated version banner for cmake.org
cca73b54ae Utilities/Sphinx: Add undocumented option to build docs for cmake.org
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7144
Reference an OpenSearch description file that sits outside the content
of any specific version so we only need to maintain one and so that
it can reference the latest version.
This was previously added in a custom branch for building the
cmake.org reference documentation.
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.
Brad King