In commit d78bfa1ecc (Utilities/Sphinx: support cmakedomain running in
parallel, 2022-10-24, v3.26.0-rc1~495^2) we declared the domain as
parallel-safe without actually implementing the required
`merge_domaindata` method. Since then, commit 37e015d4a6
(Utilities/Sphinx: Refactor Sphinx reference recording) changed how we
store resolved references, such that our separate fix for 3.26 does not
work in 3.27+.
While at it, correct a crusty comment that was overlooked during the
aforementioned refactoring.
Issue: #24076
Co-authored-by: Jared Dillard <jared.dillard@gmail.com>
Refactor commit 1f39a3cd1a (Utilities/Sphinx: Restore explicit check for
Sphinx 2.x or later) to avoid needing to suppress flake8 E402. While
ignoring it with respect to the docutils/sphinx imports and the sphinx
version check was correct, the need to disable it for the whole file was
suboptimal.
Refactoring in commit adbc8c982d (Utilities/Sphinx: Fix flake8 gripes in
cmake.py, 2023-03-13, v3.27.0-rc1~317^2) moved the assertion added by
commit cef51925a4 (Utilities/Sphinx: Require Sphinx 2.x or later,
2023-03-13, v3.27.0-rc1~317^2~2) to after imports, which is too late to
clearly reject older Sphinx versions.
When the encoding is not specified, open() may choose an encoding
based on the locale in use. That encoding may have no relationship
to the encoding of the file being opened. Use the locale from the
document settings instead, which should better match the file's
encoding.
Fixes: #24679
Edit Utilities/Sphinx/cmake.py to avoid lines longer than 79 characters
and to obey other flake8-checked style rules. This will allow using
flake8 to check for possible issues without having to wade through noise
about improper styling. (Also, of course, consistent styling is
beneficial in its own right.)
Port all uses of old-style % string formatting to use f-strings. These
are generally more readable (and tend to be shorter as well).
Although this requires Python 3.6 or later, that should be available
'stock' on most or all platforms still under support, and besides, we
were already using f-strings in some places.
Tweak our Sphinx extensions slightly to assert that Sphinx is at least
2.x. Remove hacks for older versions of Sphinx. This cleans up a bunch
of messy code and, more importantly, paves the way for consolidating our
import statements.
Add a role that can be used to create local links (a la '`LINK`_'), but
that also applies literal style. This is particularly useful for
referring to subcommands within the command's documentation in a style
that is consistent with ':command:`BAR <foo(BAR)>`' but is much less
verbose.
Although this is intended for subcommands, it works with any local
reference.
Co-authored-by: Brad King <brad.king@kitware.com>
Refactor the portion of CMakeXRefRole that escapes angle brackets in
reference titles to the equivalent of a C++ template class. This will
allow us to reuse that logic for reference roles that aren't derived
from XRefRole.
Tweak HTML styling of version-{added,changed} notes to include a hanging
indent. This makes it more obvious what text is part of such a note in
cases where the note is lengthy (especially if more than one paragraph),
rather than the relevant text blending into the surrounding prose.
Since commit cc21d0e478 (Utilities/Sphinx: Make signatures linkable,
2023-03-09) we always convert `cmake:command` domain cross-references to
use the explicit `text <text>` form. This breaks the XRefRole's
`fix_parens` setting that we use to render `cmd` as `cmd()`.
Instead, transform `cmd(sub)` to `cmd(sub) <cmd(sub)>` to preserve
the sub-command link destination, but leave `cmd` alone and let
XRefRole convert it to `cmd()`.
Split the genex directive into its own class, allowing a slight
simplification of CMakeObject. Add ability to specify an explicit target
name for the same.
Use this to provide a target for the `$<TARGET_PROPERTY:prop>` generator
expression which is otherwise missing one (due to overlap with
`$<TARGET_PROPERTY:tgt,prop>`). With this one can write:
:genex:`$<TARGET_PROPERTY:prop> <TARGET_PROPERTY:prop>`
to link the second variant.
Fixes: #24573
Implement logic to support several styles of parsing in the new
signature directive that control where line breaks are allowed in a
signature.
The default is 'smart', which forbids breaks inside of square- or
angle-brackets. The 'verbatim' option forbids all breaks. In all cases,
breaks are always allowed where a newline appears in the source.
This seems to Just Work for most writers, but HTML needs some special
handling that is accomplished by a new CSS rule and assigning the 'nbsp'
class to spaces that are not allowed to break. (ROFF's line wrapping is
rather unfortunate here, as it prefers splitting and hyphenating words
rather than breaking at a space.)
Add signatures to the collection of observed objects (which can be
referenced elsewhere). Don't automatically strip parameters from a
:command: reference, as these may now link signatures. (Do, however,
munge them into 'text <ref>' form if they aren't already, as not doing
so adds an extra '()' for some reason.) Correspondingly, change xref
resolution to try to match 'command' when a ref like 'command(args)' is
not matched, so that existing links to commands that have not been
converted to use the new signature directive don't immediately break.
Rewrite how we record objects in our Sphinx extensions to more closely
conform to how other domains do likewise, and to store more information
than was previously being stored.
This is a first step toward being able to record and reference
signatures.
Add a `signature` directive to offer a CMake version of Sphinx's
`function` directive, similar to that found in other domains (py, cpp,
etc.). Like others, this takes one or more signatures as arguments and
creates dt/dd nodes from the signatures and the directive contents.
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
