Add a Utilities/Sphinx directory to hold CMake build code to run the
Sphinx (sphinx-doc.org) documentation generation tool.  Create a
CMakeLists.txt file there capable of building either as a subdirectory
of the main CMake build, or as a standalone documentation build.

Add cache options SPHINX_MAN and SPHINX_HTML to select output formats
and SPHINX_EXECUTABLE to specify the sphinx-build executable.  Add
bootstrap options --sphix-man and --sphinx-html to select output formats
and --sphinx-build=<sb> to specify the sphinx-build executable.

Create a "conf.py.in" file to configure_file into "conf.py" to tell
sphinx-build how to build our documents.  Create a "cmake.py" Sphinx
extension module defining:

* The "cmake-module" directive used in Help/module/*.rst files to
  scan .rst markup from the corresponding Modules/*.cmake file.

* A Sphinx domain called "cmake" defining documentation object types
  for CMake Help/<type> directories: command, generator, manual,
  module, policy, prop_*, and variable.  Add a "role" for each type
  to perform cross-references.  Teach the roles to treat "<XYZ>"
  as placeholders instead of explicit targets if not preceded by
  a space.  Add cmake domain directives to define command and
  variable objects explicitly in .rst file content.  This will
  allow modules to define their own commands and variables and
  have them indexed and linkable.

* A Sphinx document transform that converts Help/<type>/*.rst documents
  into cmake domain objects of the corresponding <type> and adds index
  entries for them.  This will automatically index all CMake documentation
  objects and provide cross-reference targets for them with no special
  markup in the .rst files.

Now that all DefineProperty documentation calls have been dropped, drop
the supporting APIs.

We need only 'Brief' for usage documentation.  We no longer have builtin
'Full' documentation, which is now in Help/*/*.rst files.

Drop all GetTerseDocumentation and GetFullDocumentation methods from
commands.  The command documentation is now in Help/command/*.rst files.

Drop all DefineProperty calls for non-chained properties.  Drop the
documentation from the chained ones.  The documentation for all
properties is now in Help/prop_*/*.rst files.

Property documentation is no longer builtin, so the get_property command
will be unable to return the documentation.  Drop the test for it.

We now need only the Usage formatter to support command-line options
that print basic usage, and the supporting indented=>preformatted markup
processor to support CMake message formatting.  Drop all other
documentation formatters and move the remaining code up into the top
cmDocumentationFormatter class.

These checks want to know if named target properties are builtin, which
is now known by checking the Help/prop_tgt directory.  (Previously the
check could be confused by a define_property call in the project.)

Install the Help directory next to Modules to make it available in CMake
distributions.  Use cmRST to read Help .rst documents and print them as
help output.

Add options

 --help-manual-list
 --help-manual

to list available manuals or print one of them.  Implement the options

 --help-commands
 --help-modules
 --help-policies
 --help-properties
 --help-variables

by mapping to the corresponding manual page.  Implement the options

 --help-command-list
 --help-module-list
 --help-policy-list
 --help-property-list
 --help-variable-list

by globbing the available Help .rst documents of the corresponding type
and reading their titles.  Implement the options

 --help-command
 --help-module
 --help-policy
 --help-property
 --help-variable

by globbing the matching Help .rst document(s) and printing them.

Create a cmRST class to perform just enough reStructuredText processing
to support display of Help documents in human-readable text format.
This will be used to implement --help-* command-line options.

Support directives "include", "replace", "parsed-literal", "toctree"
(Sphinx), and "cmake-module" (CMake Sphinx Extension to scan .cmake
modules).  Support inline CMake Sphinx Domain roles to convert
cross-references to corresponding title text.  Support inline
substitutions defined by the "replace" directive, but keep it simple by
requiring replacements to be defined before use.

Add a CMakeLib "testRST" case to cover processing of supported
constructs and compare results against expected output.

We will no longer support full documentation generation from executables
and will instead generate documentation with other tools.  Disable (with
a warning left behind) the command-line options:

 --copyright
 --help-compatcommands
 --help-full
 --help-html
 --help-man

Drop supporting code.  Drop manual sections generation from executables.
Remove internal documentation construction APIs.  Drop unused sections
See Also, Author, Copyright, Compat Commands, Custom Modules.

Add a top-level document holding the Sphinx root toctree.  List all
reference manuals from Help/manual/*.rst and the Sphinx-generated
general index (genindex) and search pages.

This module parses its own documentation to extract supported options.
Fix the indentation level to match that expected by the parser.

Kitware Robot authored 11 years ago and Brad King committed 11 years ago

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

Create a convert-help.bash script to extract builtin documentation as
reStructuredText sources in a new Help directory.  Run each executable
with the --help-full option targeting a .rst file to extract the
documentation.  Generate Sphinx "toctree" directives to point each man
page at the corresponding documents it should contain.  Organize
cmake-commands(7), cmake-properties(7), and cmake-variables(7) man pages
into sections similar to those generated by --help-properties and
--help-variables output previously.

Kitware Robot authored 11 years ago and Brad King committed 11 years ago

Run "cmake --help-full cmake.1.rst" by hand on Windows and OS X.
Copy the generator/*.rst documents for generators unique to those
platforms into Help/generator.

Temporarily add a RST formatter to convert builtin documentation to .rst
source files.  This will be removed shortly after we use it to convert
documentation.

Teach the RST formatter to:

* Output preformatted blocks as reStructuredText "::" literal blocks.

* Output option lists as bullet lists with option names enclosed in
  reStructuredText ``literal`` quoting.

* Output individual documentation objects (commands, variables, etc.)
  in separate .rst files organized in directories by type.

Replace references to cmVersion::GetCMakeVersion() in builtin
documentation with the literal placeholder "|release|" that will be
defined as a substitution later.

This will be replaced by alternative markup later.

The property __CMAKE_DELETE_CACHE_CHANGE_VARS_ is not meant for public
exposure.

With our modern development workflow it is less likely a property will
be added to C++ code without documentation.  This mode only existed to
support the DocTest which had very limited coverage of the properties
anyway.

Drop the 'documentation' build target.  We will no longer use the
executables to generate their own documentation.  New infrastructure
will be introduced later to generate documentation.

The documentation target will be come optional, so do not reference it
when it does not exist.

Drop these tests since we will drop docbook output along with other
documentation formatters.

The latter fits more consistently with other third party integration
files.

The directory contains auxiliary support files for integration with
other tools, not documentation.

Drop the "cmake version ..." line from the top of usage and text help
formats.  Print it only when requested with --version or similar option.

All the other --help-<item> options have a corresponding option
--help-<item>-list.  Add one for --help-policy.

Factor the CMAKE_DATA_DIR, CMAKE_DOC_DIR, and CMAKE_MAN_DIR selection
out of CMakeLists.txt and into a Source/CMakeInstallDestinations.cmake
script.  Load the script from the original location of the code.

Cache the destination values as empty strings so we know if the user
sets them explicitly.  If not, then compute defaults based on the
platform and full CMake version string.  By not caching the versioned
defaults, we can change them in a single build tree as the version
changes.

Remove duplication of the install destination defaults from the
bootstrap script.  Cache empty defaults there too.  Parse from the CMake
code the default values to report in the help output.  Keep the CMake
code in a structured format to make this reliable.

Move logic to compute CMake_VERSION out of the top-level CMakeLists.txt
file to a dedicated Source/CMakeVersionCompute.cmake module and include
it from the original location.  This will allow it to be re-used.

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

eec7834e list: Fix docs for APPEND to show that elements are optional

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

2e6cadde CPackWiX: allow user supplied extra sources, objects and libraries

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

3a4a7482 CPackWiX: generate deterministic ids for directories, components and files

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

e4e5b28c cmTarget: Deprecate the LOCATION target property with a policy.

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

50762188 FindCUDA: Fix NPP library search for CUDA 5.5

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

3507d5af Deprecate COMPILE_FLAGS target property.

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

a4263c9f export(): Handle multiple dependent export sets.
66b290e7 export(): Process the export() command at generate time.
5fe5c324 export(): Set a Makefile on the cmExportBuildFileGenerator.
e3835558 cmExportInstallFileGenerator: Fix comment to match reality.

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

af1f6987 CMP0024: Store the fact of included export in global generator.

Brad King authored 11 years ago and Kitware Robot committed 11 years ago

920ffbf5 Require CMake 2.8.4 or greater to build CMake