kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
CMake/Utilities/Sphinx/CMakeLists.txt

184 lines
6.3 KiB
CMake
Raw Normal View History

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-09-18 00:08:05 +04:00
#=============================================================================
# CMake - Cross Platform Makefile Generator
# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
if(NOT CMake_SOURCE_DIR)
set(CMakeHelp_STANDALONE 1)
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.
2013-12-26 10:52:23 +04:00
cmake_minimum_required(VERSION 2.8.4 FATAL_ERROR)
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-09-18 00:08:05 +04:00
get_filename_component(tmp "${CMAKE_CURRENT_SOURCE_DIR}" PATH)
get_filename_component(CMake_SOURCE_DIR "${tmp}" PATH)
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 19:08:22 +04:00
include(${CMake_SOURCE_DIR}/Modules/CTestUseLaunchers.cmake)
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-09-18 00:08:05 +04:00
include(${CMake_SOURCE_DIR}/Source/CMakeVersionCompute.cmake)
include(${CMake_SOURCE_DIR}/Source/CMakeInstallDestinations.cmake)
unset(CMAKE_DATA_DIR)
unset(CMAKE_DATA_DIR CACHE)
endif()
project(CMakeHelp NONE)
option(SPHINX_MAN "Build man pages with Sphinx" OFF)
option(SPHINX_HTML "Build html help with Sphinx" OFF)
Utilities/Sphinx: Add option to build 'singlehtml' format Add SPHINX_SINGLEHTML to enable the Sphinx 'singlehtml' builder.
2014-04-24 22:59:34 +04:00
option(SPHINX_SINGLEHTML "Build html single page help with Sphinx" OFF)
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
option(SPHINX_QTHELP "Build Qt help with Sphinx" OFF)
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 19:09:40 +04:00
option(SPHINX_TEXT "Build text help with Sphinx (not installed)" OFF)
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-09-18 00:08:05 +04:00
find_program(SPHINX_EXECUTABLE
NAMES sphinx-build
DOC "Sphinx Documentation Builder (sphinx-doc.org)"
)
Add option to pass custom flags to sphinx-build (#15545) 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>
2015-04-30 16:30:14 +03:00
set(SPHINX_FLAGS "" CACHE STRING "Flags to pass to sphinx-build")
separate_arguments(sphinx_flags UNIX_COMMAND "${SPHINX_FLAGS}")
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-09-18 00:08:05 +04:00
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 19:09:40 +04:00
mark_as_advanced(SPHINX_TEXT)
Add option to pass custom flags to sphinx-build (#15545) 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>
2015-04-30 16:30:14 +03:00
mark_as_advanced(SPHINX_FLAGS)
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 19:09:40 +04:00
Merge branch 'master' into doc-singlehtml Resolve conflicts in Utilities/Sphinx/CMakeLists.txt by adding the help options from both sides.
2014-04-24 23:31:45 +04:00
if(NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_SINGLEHTML AND NOT SPHINX_QTHELP AND NOT SPHINX_TEXT)
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-09-18 00:08:05 +04:00
return()
elseif(NOT SPHINX_EXECUTABLE)
message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
endif()
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 18:18:57 +04:00
set(copyright_line_regex "^Copyright (2000-20[0-9][0-9] Kitware.*)")
file(STRINGS "${CMake_SOURCE_DIR}/Copyright.txt" copyright_line
LIMIT_COUNT 1 REGEX "${copyright_line_regex}")
if(copyright_line MATCHES "${copyright_line_regex}")
set(conf_copyright "${CMAKE_MATCH_1}")
else()
set(conf_copyright "Kitware, Inc.")
endif()
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 17:58:25 +04:00
set(conf_docs "${CMake_SOURCE_DIR}/Help")
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-09-18 00:08:05 +04:00
set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}")
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 23:14:29 +04:00
set(conf_version "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}")
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-09-18 00:08:05 +04:00
set(conf_release "${CMake_VERSION}")
configure_file(conf.py.in conf.py @ONLY)
set(doc_formats "")
if(SPHINX_HTML)
list(APPEND doc_formats html)
endif()
if(SPHINX_MAN)
list(APPEND doc_formats man)
endif()
Utilities/Sphinx: Add option to build 'singlehtml' format Add SPHINX_SINGLEHTML to enable the Sphinx 'singlehtml' builder.
2014-04-24 22:59:34 +04:00
if(SPHINX_SINGLEHTML)
list(APPEND doc_formats singlehtml)
endif()
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 19:09:40 +04:00
if(SPHINX_TEXT)
list(APPEND doc_formats text)
endif()
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
if(SPHINX_QTHELP)
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 23:07:53 +04:00
find_package(PythonInterp REQUIRED)
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
find_program(QCOLLECTIONGENERATOR_EXECUTABLE
NAMES qcollectiongenerator
DOC "qcollectiongenerator tool"
)
if (NOT QCOLLECTIONGENERATOR_EXECUTABLE)
message(FATAL_ERROR "QCOLLECTIONGENERATOR_EXECUTABLE (qcollectiongenerator) not found!")
endif()
list(APPEND doc_formats qthelp)
set(qthelp_extra_commands
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 21:04:28 +04:00
# Workaround for assistant prior to
# https://codereview.qt-project.org/#change,82250 in Qt 4.
COMMAND ${CMAKE_COMMAND} "-DCSS_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/_static"
-P "${CMAKE_CURRENT_SOURCE_DIR}/apply_qthelp_css_workaround.cmake"
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 12:36:43 +04:00
# Workaround sphinx configurability:
# https://bitbucket.org/birkenfeld/sphinx/issue/1448/make-qthelp-more-configurable
COMMAND ${CMAKE_COMMAND} "-DQTHELP_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
"-DCMake_VERSION=${CMake_VERSION_MAJOR}${CMake_VERSION_MINOR}${CMake_VERSION_PATCH}"
-P "${CMAKE_CURRENT_SOURCE_DIR}/fixup_qthelp_names.cmake"
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-13 17:27:59 +04:00
# Create proper identifiers. Workaround for
# https://bitbucket.org/birkenfeld/sphinx/issue/1491/qthelp-should-generate-identifiers-for
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 23:07:53 +04:00
COMMAND "${PYTHON_EXECUTABLE}"
"${CMAKE_CURRENT_SOURCE_DIR}/create_identifiers.py"
"${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
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-13 17:27:59 +04:00
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 23:07:53 +04:00
COMMAND ${QCOLLECTIONGENERATOR_EXECUTABLE}
${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qhcp
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
)
endif()
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-09-18 00:08:05 +04:00
set(doc_format_outputs "")
set(doc_format_last "")
foreach(format ${doc_formats})
set(doc_format_output "doc_format_${format}")
set(doc_format_log "build-${format}.log")
add_custom_command(
OUTPUT ${doc_format_output}
COMMAND ${SPHINX_EXECUTABLE}
-c ${CMAKE_CURRENT_BINARY_DIR}
-d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
-b ${format}
Add option to pass custom flags to sphinx-build (#15545) 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>
2015-04-30 16:30:14 +03:00
${sphinx_flags}
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-09-18 00:08:05 +04:00
${CMake_SOURCE_DIR}/Help
${CMAKE_CURRENT_BINARY_DIR}/${format}
> ${doc_format_log} # log stdout, pass stderr
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
${${format}_extra_commands}
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-09-18 00:08:05 +04:00
DEPENDS ${doc_format_last}
COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
VERBATIM
)
set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1)
list(APPEND doc_format_outputs ${doc_format_output})
set(doc_format_last ${doc_format_output})
endforeach()
add_custom_target(documentation ALL DEPENDS ${doc_format_outputs})
foreach(t
cmake
ccmake
cmake-gui
cpack
ctest
)
if(TARGET ${t})
# Build documentation after main executables.
add_dependencies(documentation ${t})
endif()
endforeach()
if(SPHINX_MAN)
file(GLOB man_rst RELATIVE ${CMake_SOURCE_DIR}/Help/manual
${CMake_SOURCE_DIR}/Help/manual/*.[1-9].rst)
foreach(m ${man_rst})
if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$")
set(name "${CMAKE_MATCH_1}")
set(sec "${CMAKE_MATCH_2}")
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/${name}.${sec}
CMake: Install COMPONENTs (sphinx-man) Added component sphinx-man
2014-12-10 01:13:42 +03:00
DESTINATION ${CMAKE_MAN_DIR}/man${sec}
COMPONENT sphinx-man)
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-09-18 00:08:05 +04:00
endif()
endforeach()
endif()
if(SPHINX_HTML)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
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 18:12:44 +04:00
DESTINATION ${CMAKE_DOC_DIR}
CMake: Install COMPONENTs Added components: - cmake - ctest - cpack - cmake-gui - ccmake - data - sphinx-html - sphinx-singlehtml - sphinx-qthelp Other now Unspecified.
2014-12-07 21:25:28 +03:00
COMPONENT sphinx-html
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 18:12:44 +04:00
PATTERN .buildinfo EXCLUDE
)
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-09-18 00:08:05 +04:00
endif()
Utilities/Sphinx: Add option to build 'singlehtml' format Add SPHINX_SINGLEHTML to enable the Sphinx 'singlehtml' builder.
2014-04-24 22:59:34 +04:00
if(SPHINX_SINGLEHTML)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/singlehtml
DESTINATION ${CMAKE_DOC_DIR}
CMake: Install COMPONENTs Added components: - cmake - ctest - cpack - cmake-gui - ccmake - data - sphinx-html - sphinx-singlehtml - sphinx-qthelp Other now Unspecified.
2014-12-07 21:25:28 +03:00
COMPONENT sphinx-singlehtml
Utilities/Sphinx: Add option to build 'singlehtml' format Add SPHINX_SINGLEHTML to enable the Sphinx 'singlehtml' builder.
2014-04-24 22:59:34 +04:00
PATTERN .buildinfo EXCLUDE
)
endif()
Merge branch 'master' into doc-singlehtml Resolve conflicts in Utilities/Sphinx/CMakeLists.txt by adding the help options from both sides.
2014-04-24 23:31:45 +04:00
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
if(SPHINX_QTHELP)
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 15:14:31 +04:00
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake-${CMake_VERSION_MAJOR}${CMake_VERSION_MINOR}${CMake_VERSION_PATCH}.qch
CMake: Install COMPONENTs Added components: - cmake - ctest - cpack - cmake-gui - ccmake - data - sphinx-html - sphinx-singlehtml - sphinx-qthelp Other now Unspecified.
2014-12-07 21:25:28 +03:00
DESTINATION ${CMAKE_DOC_DIR} COMPONENT sphinx-qthelp
Help: Add option to create and install Qt .qch file.
2014-03-31 17:44:27 +04:00
)
endif()