Configuring with `--log-level=VERBOSE` a user can see an output of
`sphinx-build` at build time.
The other way is to have `VERBOSE` envvar set at configure time.
And finally one can set `CMAKE_VERBOSE_MAKEFILE` CMake cache variable.
The `SafeString` and `ErrorString` classes are deprecated and will be
removed in Docutils 0.21 or later. They help avoid encoding errors
during exception handling in Python <= 2.7, but these days we always
use Python 3 to build the documentation, at least during development,
when error cases are most likely to occur.
Fixes: #24039
The QtHelp Sphinx generation code contains two links to Sphinx issues
that used old, dead BitBucket URLs. Those issues were migrated to
GitHub, so the dead links can be replaced with working ones.
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.
In particular, guarantee that policy `CMP0077` has `NEW` behavior.
This will be useful to hard-code options of third-party libraries
without polluting our own cache.
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.
Brad King