Commit Graph

20 Commits

Author SHA1 Message Date
Brad King faf291a9c4 Utilities/Sphinx: Add option to build 'singlehtml' format
Add SPHINX_SINGLEHTML to enable the Sphinx 'singlehtml' builder.
2014-04-24 15:23:27 -04:00
Brad King d55671ad9d Utilities/Sphinx: Fix cmake domain document removal with python3
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.
2014-04-24 09:04:52 -04:00
Uwe L. Korn 69069cfb1a Utilities/Sphinx: Port documentation generation to python3 (#14886) 2014-04-18 08:42:34 -04:00
Brad King 34ea1f1520 Utilities/Sphinx: Add option to build 'text' format
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.
2014-02-04 10:29:05 -05:00
Brad King 0c3cf36b3a Help: Do not install Sphinx html build info files
Exclude '.buildinfo' and 'objects.inv' from installation as part
of the Sphinx-generated html documentation.
2014-01-28 09:12:44 -05:00
Stephen Kelly 0de81bba8c Help: Workaround pygments reporting an error for genexes.
Without the workaround, CMake code snippets are not highlighted
at all because pygments can not lex the generator expressions.
2014-01-04 11:28:56 +01:00
Stephen Kelly 0cf550b2ca Help: Remove workaround for pre-CMake 2.8.4 code.
The requirement was updated in commit 920ffbf5 (Require CMake 2.8.4
or greater to build CMake, 2013-10-11) and similar snippets were
removed.
2014-01-04 11:28:56 +01:00
Alex Neundorf fb107d84d2 Help: Fix Sphinx extension with docutils < 0.11
In older versions of python docutils "error_reporting" was not in the
"utils" subpackage, so try the older location if the new one failed.

Alex
2013-12-23 10:17:01 -05:00
Brad King 3bade75b02 Help: Parse Copyright.txt instead of using current year
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.
2013-11-13 09:18:57 -05:00
Brad King a023a26cad Help: Configure html favicon 2013-11-05 08:59:02 -05:00
Brad King fb332197bf Help: Configure html page navigation bars
Add a small CMake logo to the left side of the header and footer
navigation bars.  Set the html theme, title, and short title explicitly.
2013-11-05 08:58:56 -05:00
Brad King e1f819664b Help: Configure |version| replacement correctly
Fix our configuration of the Sphinx conf.py 'version' entry to refer
to the correctly-spelled CMake_VERSION_(MAJOR|MINOR|PATCH) variables.
2013-11-04 14:22:27 -05:00
Brad King edc7cc967d Help: Configure copyright year automatically
Teach our Sphinx conf.py to compute the copyright end year
automatically.  Drop our hard-coded configuration for it.
2013-11-04 14:22:23 -05:00
Brad King 4abe0ec211 Merge topic 'doc-conf-auto-manuals'
f88332f Help: Glob manual/*.rst in Sphinx configuration
2013-10-30 10:25:27 -04:00
Brad King f88332f5b7 Help: Glob manual/*.rst in Sphinx configuration
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.
2013-10-30 09:58:25 -04:00
Brad King 10ef247b88 Configure Utilities/Sphinx for standalone build with CTest
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.
2013-10-29 11:11:39 -04:00
Brad King 2945814de2 cmRST: Teach cmake-module directive to scan bracket comments
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.
2013-10-23 09:36:00 -04:00
Brad King 80a311ed6a Help: Add cmake-developer.7 manual
Add the manual with just an introduction section.  Leave section headers
for Help and Modules to be filled in later.
2013-10-22 09:50:15 -04:00
Brad King e7ca48f226 Help: Factor out cmake-generator-expressions manual page
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.
2013-10-16 09:22:38 -04:00
Brad King bfe07aa97e Build Help documentation during CMake build using Sphinx
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.
2013-10-16 09:22:37 -04:00