Commit a8c88421 authored by Brad King's avatar Brad King 💬 Committed by Kitware Robot
Browse files

Merge topic 'doc-cmake.org-tutorial-archive' into release-3.23

4cb616fe Tutorial: Provide a source archive when published on cmake.org
37fb7059 Utilities/Sphinx: Add variables listing pre-sphinx commands
eb7d913a

 Utilities/Sphinx: Clarify names of variables listing post-sphinx commands
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !7215
parents 74c4762a 4cb616fe
......@@ -4,6 +4,8 @@
*.user*
*.pyc
Help/_generated
Testing
CMakeUserPresets.json
......
......@@ -11,8 +11,9 @@ work together in an example project can be very helpful.
Steps
=====
The tutorial documentation and source code for examples can be found in
the ``Help/guide/tutorial`` directory of the CMake source code tree.
.. include:: source.txt
|tutorial_source|
Each step has its own subdirectory containing code that may be used as a
starting point. The tutorial examples are progressive so that each step
provides the complete solution for the previous step.
......
.. |tutorial_source| replace::
The tutorial documentation and source code examples can be found in
the ``Help/guide/tutorial`` directory of the CMake source code tree.
......@@ -68,7 +68,7 @@ if(SPHINX_HTML)
# we provide the path to the produced html output in the console
# for tools that support URI protocol schemes
set(html_extra_commands
set(html_post_commands
COMMAND ${CMAKE_COMMAND} -E echo "sphinx-build html: HTML documentation generated in file://${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
)
......@@ -94,7 +94,7 @@ if(SPHINX_INFO)
# Sphinx texinfo builder supports .info, .txt, .html and .pdf output.
# SPHINX_INFO controls the .info output.
set(texinfo_extra_commands
set(texinfo_post_commands
COMMAND ${MAKEINFO_EXECUTABLE} --no-split -o
${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.info
${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.texi
......@@ -112,7 +112,7 @@ if(SPHINX_QTHELP)
endif()
list(APPEND doc_formats qthelp)
set(qthelp_extra_commands
set(qthelp_post_commands
# 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"
......@@ -148,7 +148,11 @@ if(CMake_SPHINX_CMAKE_ORG)
list(APPEND doc_html_opts -A outdated=1)
endif()
list(APPEND qthelp_extra_commands
list(APPEND html_pre_commands
COMMAND ${CMAKE_COMMAND} -Dversion=${CMake_VERSION} -P ${CMAKE_CURRENT_SOURCE_DIR}/tutorial_archive.cmake
)
list(APPEND qthelp_post_commands
COMMAND ${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch"
"${CMAKE_CURRENT_BINARY_DIR}/html/CMake.qch"
......@@ -170,6 +174,7 @@ foreach(format ${doc_formats})
# arguments in peculiar order
add_custom_command(
OUTPUT ${doc_format_output}
${${format}_pre_commands}
COMMAND ${SPHINX_EXECUTABLE}
-M ${format}
${CMake_SOURCE_DIR}/Help
......@@ -179,7 +184,7 @@ foreach(format ${doc_formats})
${sphinx_flags}
${doc_${format}_opts}
> ${doc_format_log} # log stdout, pass stderr
${${format}_extra_commands}
${${format}_post_commands}
DEPENDS ${doc_format_last}
COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
VERBATIM
......@@ -188,6 +193,7 @@ foreach(format ${doc_formats})
# other formats use standard builder (-b) mode
add_custom_command(
OUTPUT ${doc_format_output}
${${format}_pre_commands}
COMMAND ${SPHINX_EXECUTABLE}
-c ${CMAKE_CURRENT_BINARY_DIR}
-d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
......@@ -197,7 +203,7 @@ foreach(format ${doc_formats})
${CMake_SOURCE_DIR}/Help
${CMAKE_CURRENT_BINARY_DIR}/${format}
> ${doc_format_log} # log stdout, pass stderr
${${format}_extra_commands}
${${format}_post_commands}
DEPENDS ${doc_format_last}
COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
VERBATIM
......
if(NOT version)
message(FATAL_ERROR "Pass -Dversion=")
endif()
# Name of the archive and its top-level directory.
set(archive_name "cmake-${version}-tutorial-source")
# Base directory for CMake Documentation.
set(help_dir "${CMAKE_CURRENT_LIST_DIR}/../../Help")
cmake_path(ABSOLUTE_PATH help_dir NORMALIZE)
# Collect the non-documentation part of the tutorial directory.
file(COPY "${help_dir}/guide/tutorial/"
DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}"
NO_SOURCE_PERMISSIONS
PATTERN *.rst EXCLUDE
PATTERN source.txt EXCLUDE
)
file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}/README.txt" [[
This directory contains source code examples for the CMake Tutorial.
Each step has its own subdirectory containing code that may be used as a
starting point. The tutorial examples are progressive so that each step
provides the complete solution for the previous step.
]])
# Create an archive containing the tutorial source examples.
file(MAKE_DIRECTORY "${help_dir}/_generated")
file(ARCHIVE_CREATE
OUTPUT "${help_dir}/_generated/${archive_name}.zip"
PATHS "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}"
FORMAT zip
)
# Write a reStructuredText snippet included from the tutorial index.
file(WRITE "${help_dir}/guide/tutorial/source.txt" "
.. |tutorial_source| replace::
The tutorial source code examples are available in
:download:`this archive </_generated/${archive_name}.zip>`.
")
# Remove temporary directory.
file(REMOVE_RECURSE "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}")
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment