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

4cb616fed6 Tutorial: Provide a source archive when published on cmake.org
37fb70591e Utilities/Sphinx: Add variables listing pre-sphinx commands
eb7d913a21 Utilities/Sphinx: Clarify names of variables listing post-sphinx commands

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7215

.gitignore

@@ -4,6 +4,8 @@
 *.user*
 
 *.pyc
+
+Help/_generated
 Testing
 CMakeUserPresets.json
 

Help/guide/tutorial/index.rst

@@ -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.

Help/guide/tutorial/source.txt

@@ -0,0 +1,3 @@
+.. |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.

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,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

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 </_generated/${archive_name}.zip>`.
+")
+
+# Remove temporary directory.
+file(REMOVE_RECURSE "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}")