From eb7d913a219627dbaae178c1b487f01990cc0572 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 27 Apr 2022 13:25:44 -0400 Subject: Utilities/Sphinx: Clarify names of variables listing post-sphinx commands --- Utilities/Sphinx/CMakeLists.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Utilities/Sphinx') diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index d2bfb61976..8265ce41ef 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -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,7 @@ if(CMake_SPHINX_CMAKE_ORG) list(APPEND doc_html_opts -A outdated=1) endif() - list(APPEND qthelp_extra_commands + list(APPEND qthelp_post_commands COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch" "${CMAKE_CURRENT_BINARY_DIR}/html/CMake.qch" @@ -179,7 +179,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 @@ -197,7 +197,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 -- cgit v1.2.1 From 37fb70591ebd06d8434eb7a650aeaae17b2380e2 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 27 Apr 2022 14:58:09 -0400 Subject: Utilities/Sphinx: Add variables listing pre-sphinx commands --- Utilities/Sphinx/CMakeLists.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Utilities/Sphinx') diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index 8265ce41ef..f77bab4073 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -170,6 +170,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 @@ -188,6 +189,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} -- cgit v1.2.1 From 4cb616fed63a93547e81812980d59660bdf9757f Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 27 Apr 2022 15:02:44 -0400 Subject: Tutorial: Provide a source archive when published on cmake.org Provide readers following the tutorial on `cmake.org` a direct link to download the tutorial's source examples. Previously readers had to fetch the CMake source tree separately and look for the tutorial source examples inside it. Fixes: #22475 --- Utilities/Sphinx/CMakeLists.txt | 4 ++++ Utilities/Sphinx/tutorial_archive.cmake | 42 +++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 Utilities/Sphinx/tutorial_archive.cmake (limited to 'Utilities/Sphinx') diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index f77bab4073..51c035e9ee 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -148,6 +148,10 @@ if(CMake_SPHINX_CMAKE_ORG) list(APPEND doc_html_opts -A outdated=1) endif() + 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" diff --git a/Utilities/Sphinx/tutorial_archive.cmake b/Utilities/Sphinx/tutorial_archive.cmake new file mode 100644 index 0000000000..212a6220e7 --- /dev/null +++ b/Utilities/Sphinx/tutorial_archive.cmake @@ -0,0 +1,42 @@ +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 `. +") + +# Remove temporary directory. +file(REMOVE_RECURSE "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}") -- cgit v1.2.1