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.
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.
The value must be either a full path or relative to the configuration
directory, not relative to the 'static' directory. Use a full path.
This avoids a warning:
WARNING: favicon file 'cmake-favicon.ico' does not exist
It worked before because all 'static' directory content is copied to the
'_static' directory of html output anyway.
Explicitly invoke python script through the interpreter since
windows does not act on hashbangs.
Use the found qcollectiongenerator executable rather than what
happens to be in PATH.
Add identifiers for variables, properties, policies and modules.
This will allow QtCreator to show relevant documentation if it learns
more about the context of the contents of cmake files.
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.
Assistant in Qt 4.8 does not handle css import paths relative to
the includer. This is fixed in Qt 4.8 commit b95750a275 (Assistant: Set
the url on created QNetworkReply objects., 2014-03-31). It is unknown
whether there will be a further Qt 4.8 release containing that commit.
Use a CMake script to pre-replace the content prior to generating the
qch file. An alternative workaround of moving the files or adding
"_static" to the import path did not seem to work for existing Qt 4.8
versions.
The bug was fixed in the Qt 5 branch before Qt 5.0. The Qt 5 assistant
renders this workaround'ed version correctly too.
Add SPHINX_TEXT to enable the Sphinx 'text' builder. Mark it as
advanced and do not add install rules. This is intended for use
by the release manager to build the release notes in text format
suitable for email.
Configure our Sphinx conf.py with a copyright line extracted from
Copyright.txt instead of using the year in which the documentation is
built. This will future-proof the reported copyright year range when
building documentation for old versions.
Add the man page description line as explicit markup at the top of each
Help/manual/*.rst file and scan it from conf.py to automatically
generate the man_pages Sphinx configuration value. This reduces the
number of places that need to be changed when a new manual is added.
Include the CTestUseLaunchers module in the standalone build of
Utilities/Sphinx so that it can be built under CTest with the
CTEST_USE_LAUNCHERS option.
When scanning CMake module files for .rst comments, recognize
bracket comments starting in ".rst:" too. For example:
#[[.rst:
Include the bracket comment content terminated by the closing bracket.
Exclude the line containing the bracket if it starts in "#".
Teach the CMakeLib.testRST test to cover multiple bracket lengths
and ending brackets on lines with and without "#".
Update the cmake-developer.7 manual to document the bracket-comment
syntax for .rst documentation.
Generator expressions are supported in many places and are a distinct
concept worthy of their own manual page. The old builtin documentation
was previously represented by preprocessor macros to generate it into
each place that supports them. Factor out the duplicate content into a
dedicated cmake-generator-expressions manual page and reference it from
each original location.
