From 4cb616fed63a93547e81812980d59660bdf9757f Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
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
---
 .gitignore                              |  2 ++
 Help/guide/tutorial/index.rst           |  5 ++--
 Help/guide/tutorial/source.txt          |  3 +++
 Utilities/Sphinx/CMakeLists.txt         |  4 ++++
 Utilities/Sphinx/tutorial_archive.cmake | 42 +++++++++++++++++++++++++++++++++
 5 files changed, 54 insertions(+), 2 deletions(-)
 create mode 100644 Help/guide/tutorial/source.txt
 create mode 100644 Utilities/Sphinx/tutorial_archive.cmake

diff --git a/.gitignore b/.gitignore
index d39684d..be848fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,8 @@
 *.user*
 
 *.pyc
+
+Help/_generated
 Testing
 CMakeUserPresets.json
 
diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst
index 8b20a2d..09553cb 100644
--- a/Help/guide/tutorial/index.rst
+++ b/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.
diff --git a/Help/guide/tutorial/source.txt b/Help/guide/tutorial/source.txt
new file mode 100644
index 0000000..bb45e86
--- /dev/null
+++ b/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.
diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt
index f77bab4..51c035e 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 0000000..212a622
--- /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 </_generated/${archive_name}.zip>`.
+")
+
+# Remove temporary directory.
+file(REMOVE_RECURSE "${CMAKE_CURRENT_BINARY_DIR}/${archive_name}")
-- 
cgit v0.12