Since commit 37e015d4a6 (Utilities/Sphinx: Refactor Sphinx reference
recording, 2023-03-08, v3.27.0-rc1~342^2~1), anchors in links to cmake
domain objects generated in html search results were missing their
object type prefix, and thus did not link to the object.
Restore our `get_objects` implementation's second tuple entry to what we
used prior to that commit. This matches what Sphinx's builtin python,
rst, and javascript modes do.
Fixes: #25067
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.
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.
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
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.
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.
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.
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.
Sphinx 1.4 introduced a breaking change to `indexnode` by changing
the length of a tuple. Teach our extension to produce a tuple of
the proper length for the version of Sphinx in use.
This gets rid of the "4 column based index found" warning.
Per-source copyright/license notice headers that spell out copyright holder
names and years are hard to maintain and often out-of-date or plain wrong.
Precise contributor information is already maintained automatically by the
version control tool. Ultimately it is the receiver of a file who is
responsible for determining its licensing status, and per-source notices are
merely a convenience. Therefore it is simpler and more accurate for
each source to have a generic notice of the license name and references to
more detailed information on copyright holders and full license terms.
Our `Copyright.txt` file now contains a list of Contributors whose names
appeared source-level copyright notices. It also references version control
history for more precise information. Therefore we no longer need to spell
out the list of Contributors in each source file notice.
Replace CMake per-source copyright/license notice headers with a short
description of the license and links to `Copyright.txt` and online information
available from "https://cmake.org/licensing". The online URL also handles
cases of modules being copied out of our source into other projects, so we
can drop our notices about replacing links with full license text.
Run the `Utilities/Scripts/filter-notices.bash` script to perform the majority
of the replacements mechanically. Manually fix up shebang lines and trailing
newlines in a few files. Manually update the notices in a few files that the
script does not handle.
When a CMake domain 'command' object is defined by CMakeTransform or the
'cmake:command' directive, generate the link target with a lower-case
name even if the command name is not all lower-case. This is needed to
make cross-references to the command definition work since the
'cmake:command' role is marked with the 'lowercase' property.
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.
Teach set_property and get_property an "INSTALL" property type to be
associated with install-tree file paths. Make the properties available
to CPack for use during packaging. Add a "prop_inst" Sphinx domain
object type for documentation of such properties.
In the domain clear_doc method, avoid removing entries from a dictionary
while iterating over it. Instead accumulate a set of entries to remove
at the end.
