Commit Graph

36 Commits

Author SHA1 Message Date
Brad King b3bbb6550e Merge branch 'doc-index-xrefs' into release 2014-11-12 09:17:01 -05:00
Brad King 7ca9a459eb Utilities/Sphinx: Add index entries for cross-references
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.
2014-11-12 09:10:52 -05:00
Brad King 4c8c442d7c Help: Fix broken cross-references reported by 'nitpicky' option
Enable the Sphinx 'nitpicky' option and fix the resulting warnings about
dangling references.
2014-11-07 11:41:21 -05:00
Brad King 5088e0a048 Utilities/Sphinx: Fix html_favicon configuration
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.
2014-11-07 09:50:50 -05:00
Nils Gladitz 9e5e7e71c5 Help: Fix QtHelp commands on Windows
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.
2014-07-28 21:07:53 +02:00
Stephen Kelly 376ba93588 Help: Identify more artifact types in QtHelp documentation.
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.
2014-07-17 16:05:10 +02:00
Stephen Kelly d107949d21 Help: Add context to titles in QtHelp.
This allows disambiguation of identifiers in Qt Assistant and Creator.
2014-06-17 11:28:00 +02:00
Stephen Kelly b5002631c0 Help: Create proper identifiers for keywords in QtHelp.
This is necessary in order for the QHelpEngineCore::linksForIdentifier API
to work.

 http://doc-snapshot.qt-project.org/qt5-5.3/qhelpenginecore.html#linksForIdentifier

That API is used by QtCreator to enable contextual links to help files.
2014-06-17 11:06:48 +02:00
Nils Gladitz 15a8af21e8 Add an "installed file" property scope
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.
2014-05-28 12:28:18 -04:00
Brad King aaa6c8a6ce Merge branch 'master' into doc-singlehtml
Resolve conflicts in Utilities/Sphinx/CMakeLists.txt by adding the help
options from both sides.
2014-04-24 15:31:45 -04:00
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 3c8226e590 Merge topic 'sphinx-python3'
d55671ad Utilities/Sphinx: Fix cmake domain document removal with python3
2014-04-24 09:24:59 -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
Brad King e0790c90c0 Merge topic 'sphinx-python3'
69069cfb Utilities/Sphinx: Port documentation generation to python3 (#14886)
2014-04-18 09:08:28 -04:00
Uwe L. Korn 69069cfb1a Utilities/Sphinx: Port documentation generation to python3 (#14886) 2014-04-18 08:42:34 -04:00
Stephen Kelly 6578508ca3 Help: Fix installation of the Qt qch file.
The file was changed to have the version in its name in
commit 111bb67c (Help: Use a more-appropriate qthelp namespace and
file name., 2014-04-10).
2014-04-14 13:14:31 +02:00
Stephen Kelly 111bb67c14 Help: Use a more-appropriate qthelp namespace and file name.
Use the namespace org.cmake instead of org.sphinx.cmake. Add the
version to the output file name.
2014-04-10 17:30:57 +02:00
Stephen Kelly 3a572290cc Help: Workaround Qt 4.8 assistant bug in CSS handling.
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.
2014-04-01 19:45:08 +02:00
Stephen Kelly 85582d14fe Help: Add option to create and install Qt .qch file. 2014-03-31 23:55:08 +02: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