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.
Previously we made the `documentation` target depend on the executable
targets. There is no real reason to do this other than serializing the
documentation build output in terminals. Move this dependency behind an
undocumented option so that it is not on by default.
Teach Sphinx and our own install rules to skip a `Help/dev` directory.
This will give us a place to put developer-only documentation that
should not be included in the user-facing documentation. Add a
placeholder README.
30abf145 Help: Fix cmake code block warnings produced by Sphinx 1.4
97917900 Utilities/Sphinx: Port qthelp css workaround to Sphinx 1.4
971384c2 Utilities/Sphinx: Port cmake extension to Sphinx 1.4
The `default.css` static content is no longer placed in the qthelp
`_static` directory. If it does not exist, skip over it and insert
the content of `basic.css` directly into `cmake.css`.
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.
Leave the option undocumented since it is not for general use. We can
simply pass it through `SPHINX_FLAGS` when building for publication on
`cmake.org`.
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.
The latter is now the preferred URL for visiting cmake.org with a
browser. Convert using the shell code:
git ls-files -z | xargs -0 sed -i 's|http://www\.cmake|https://cmake|g'
Create a SPHINX_FLAGS cache entry that users can populate with
command-line flags for sphinx-build. Add an option to the
bootstrap script to populate it up front.
Suggested-by: Felix Geyer <debfx@ubuntu.com>
To link CMake documentation from other documentation sets
like KDE extra-cmake-modules the intersphinx extension depends
on the objects.inv mapping file. The size overhead of 14k seems
to be neglectable.
Signed-off-by: Gregor Jasny <gjasny@googlemail.com>
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.
