Modules/Documentation: remove

This is an old module from when VTK and other Kitware projects drove the
addition of commands and modules into CMake itself. Modern VTK doesn't
need this module and it can be ignored.

This module is kept around so that the ancient VTK versions which use it
are not broken by it. VTK itself stopped using the module in 2012 and
the last usage by an example in VTK was removed in 2020.

Fixes: #20591

21 files changed, 170 insertions, 1 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index ffb4543..3f3b70d 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.18
 .. toctree::
    :maxdepth: 1
 
+   CMP0106: The Documentation module is removed. </policy/CMP0106>
    CMP0105: Device link step uses the link options. </policy/CMP0105>
    CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104>
    CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103>
diff --git a/Help/policy/CMP0106.rst b/Help/policy/CMP0106.rst
new file mode 100644
index 0000000..e34d15a
--- /dev/null
+++ b/Help/policy/CMP0106.rst
@@ -0,0 +1,19 @@
+CMP0106
+-------
+
+The :module:`Documentation` module is removed.
+
+The :module:`Documentation` was added as a support mechanism for the VTK
+project and was tuned for that project. Instead of CMake providing this module
+with (now old) VTK patterns for cache variables and required packages, the
+module is now deprecated by CMake itself.
+
+The ``OLD`` behavior of this policy is for :module:`Documentation` to add
+cache variables and find VTK documentation dependent packages. The ``NEW``
+behavior is to act as an empty module.
+
+This policy was introduced in CMake version 3.18.  CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/deprecate-documentation-module.rst b/Help/release/dev/deprecate-documentation-module.rst
new file mode 100644
index 0000000..5c3157b
--- /dev/null
+++ b/Help/release/dev/deprecate-documentation-module.rst
@@ -0,0 +1,6 @@
+deprecate-documentation-module
+------------------------------
+
+* The :module:`Documentation` module has been deprecated via
+  :policy:`CMP0106`. This module was essentially VTK code that CMake should
+  not be shipping anymore.
diff --git a/Modules/Documentation.cmake b/Modules/Documentation.cmake
index aaf24f6..c297231 100644
--- a/Modules/Documentation.cmake
+++ b/Modules/Documentation.cmake
@@ -9,6 +9,30 @@ This module provides support for the VTK documentation framework.  It
 relies on several tools (Doxygen, Perl, etc).
 #]=======================================================================]
 
+cmake_policy(GET CMP0106 _Documentation_policy)
+
+if (_Documentation_policy STREQUAL "NEW")
+  message(FATAL_ERROR
+    "Documentation.cmake is VTK-specific code and should not be used in "
+    "non-VTK projects. This logic in this module is best shipped with the "
+    "project using it rather than with CMake. This is now an error according "
+    "to policy CMP0106.")
+else ()
+
+if (_Documentation_policy STREQUAL "")
+  # Ignore the warning if the project is detected as VTK itself.
+  if (NOT CMAKE_PROJECT_NAME STREQUAL "VTK" AND
+      NOT PROJECT_NAME STREQUAL "VTK")
+    cmake_policy(GET_WARNING CMP0106 _Documentation_policy_warning)
+    message(AUTHOR_WARNING
+      "${_Documentation_policy_warning}\n"
+      "Documentation.cmake is VTK-specific code and should not be used in "
+      "non-VTK projects. This logic in this module is best shipped with the "
+      "project using it rather than with CMake.")
+  endif ()
+  unset(_Documentation_policy_warning)
+endif ()
+
 #
 # Build the documentation ?
 #
@@ -44,3 +68,7 @@ if (BUILD_DOCUMENTATION)
   #
 
 endif ()
+
+endif ()
+
+unset(_Documentation_policy)
diff --git a/Source/cmIncludeCommand.cxx b/Source/cmIncludeCommand.cxx
index 019483e..ae801bb 100644
--- a/Source/cmIncludeCommand.cxx
+++ b/Source/cmIncludeCommand.cxx
@@ -19,6 +19,9 @@ bool cmIncludeCommand(std::vector<std::string> const& args,
                       cmExecutionStatus& status)
 {
   static std::map<std::string, cmPolicies::PolicyID> DeprecatedModules;
+  if (DeprecatedModules.empty()) {
+    DeprecatedModules["Documentation"] = cmPolicies::CMP0106;
+  }
 
   if (args.empty() || args.size() > 4) {
     status.SetError("called with wrong number of arguments.  "
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index cdf3f71..4abfa1f 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -314,7 +314,9 @@ class cmMakefile;
          "CUDA_ARCHITECTURES not allowed.",                                   \
          3, 18, 0, cmPolicies::WARN)                                          \
   SELECT(POLICY, CMP0105, "Device link step uses the link options.", 3, 18,   \
-         0, cmPolicies::WARN)
+         0, cmPolicies::WARN)                                                 \
+  SELECT(POLICY, CMP0106, "The Documentation module is removed.", 3, 18, 0,   \
+         cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \
diff --git a/Tests/RunCMake/CMP0106/CMP0106-Common.cmake b/Tests/RunCMake/CMP0106/CMP0106-Common.cmake
new file mode 100644
index 0000000..a1f7908
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-Common.cmake
@@ -0,0 +1,10 @@
+include(Documentation OPTIONAL RESULT_VARIABLE found)
+if (NOT should_find AND found)
+  message(FATAL_ERROR
+    "The Documentation module should not have been found, but it was.")
+endif ()
+if (should_find AND NOT found)
+  message(FATAL_ERROR
+    "The Documentation module should have been found, but it was not.")
+endif ()
+include(${CMAKE_ROOT}/Modules/Documentation.cmake)
diff --git a/Tests/RunCMake/CMP0106/CMP0106-NEW-result.txt b/Tests/RunCMake/CMP0106/CMP0106-NEW-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-NEW-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/CMP0106/CMP0106-NEW-stderr.txt b/Tests/RunCMake/CMP0106/CMP0106-NEW-stderr.txt
new file mode 100644
index 0000000..7ad774e
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-NEW-stderr.txt
@@ -0,0 +1,9 @@
+CMake Error at .*/Modules/Documentation.cmake:15 \(message\):
+  Documentation.cmake is VTK-specific code and should not be used in non-VTK
+  projects.  This logic in this module is best shipped with the project using
+  it rather than with CMake.  This is now an error according to policy
+  CMP0106.
+Call Stack \(most recent call first\):
+  CMP0106-Common.cmake:10 \(include\)
+  CMP0106-NEW.cmake:4 \(include\)
+  CMakeLists.txt:7 \(include\)
diff --git a/Tests/RunCMake/CMP0106/CMP0106-NEW.cmake b/Tests/RunCMake/CMP0106/CMP0106-NEW.cmake
new file mode 100644
index 0000000..e7d5bd1
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-NEW.cmake
@@ -0,0 +1,4 @@
+cmake_policy(SET CMP0106 NEW)
+
+set(should_find OFF)
+include(CMP0106-Common.cmake)
diff --git a/Tests/RunCMake/CMP0106/CMP0106-OLD.cmake b/Tests/RunCMake/CMP0106/CMP0106-OLD.cmake
new file mode 100644
index 0000000..730e846
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-OLD.cmake
@@ -0,0 +1,9 @@
+cmake_policy(SET CMP0106 OLD)
+
+set(should_find ON)
+include(CMP0106-Common.cmake)
+if (NOT DEFINED BUILD_DOCUMENTATION)
+  message(FATAL_ERROR
+    "Cache variables seem to have not been made with a `OLD` policy "
+    "setting.")
+endif ()
diff --git a/Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView-stderr.txt b/Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView-stderr.txt
new file mode 100644
index 0000000..b61889b
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView-stderr.txt
@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at CMP0106-Common.cmake:1 \(include\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+Call Stack \(most recent call first\):
+  subdir/CMakeLists.txt:2 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
diff --git a/Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView.cmake b/Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView.cmake
new file mode 100644
index 0000000..309abcc
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView.cmake
@@ -0,0 +1,2 @@
+set(should_find ON)
+add_subdirectory(subdir)
diff --git a/Tests/RunCMake/CMP0106/CMP0106-WARN-VTK-stderr.txt b/Tests/RunCMake/CMP0106/CMP0106-WARN-VTK-stderr.txt
new file mode 100644
index 0000000..f8a754e
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-WARN-VTK-stderr.txt
@@ -0,0 +1,9 @@
+CMake Warning \(dev\) at CMP0106-Common.cmake:1 \(include\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+Call Stack \(most recent call first\):
+  CMP0106-WARN-VTK.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
diff --git a/Tests/RunCMake/CMP0106/CMP0106-WARN-VTK.cmake b/Tests/RunCMake/CMP0106/CMP0106-WARN-VTK.cmake
new file mode 100644
index 0000000..99f6c39
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-WARN-VTK.cmake
@@ -0,0 +1,2 @@
+set(should_find ON)
+include(CMP0106-Common.cmake)
diff --git a/Tests/RunCMake/CMP0106/CMP0106-WARN-stderr.txt b/Tests/RunCMake/CMP0106/CMP0106-WARN-stderr.txt
new file mode 100644
index 0000000..d0d48d0
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-WARN-stderr.txt
@@ -0,0 +1,37 @@
+CMake Warning \(dev\) at CMP0106-Common.cmake:1 \(include\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+Call Stack \(most recent call first\):
+  CMP0106-WARN.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
+
+CMake Warning \(dev\) at .*/Modules/Documentation.cmake:27 \(message\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+  Documentation.cmake is VTK-specific code and should not be used in non-VTK
+  projects.  This logic in this module is best shipped with the project using
+  it rather than with CMake.
+Call Stack \(most recent call first\):
+  CMP0106-Common.cmake:1 \(include\)
+  CMP0106-WARN.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
+
+CMake Warning \(dev\) at .*/Modules/Documentation.cmake:27 \(message\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+  Documentation.cmake is VTK-specific code and should not be used in non-VTK
+  projects.  This logic in this module is best shipped with the project using
+  it rather than with CMake.
+Call Stack \(most recent call first\):
+  CMP0106-Common.cmake:10 \(include\)
+  CMP0106-WARN.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
diff --git a/Tests/RunCMake/CMP0106/CMP0106-WARN.cmake b/Tests/RunCMake/CMP0106/CMP0106-WARN.cmake
new file mode 100644
index 0000000..99f6c39
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMP0106-WARN.cmake
@@ -0,0 +1,2 @@
+set(should_find ON)
+include(CMP0106-Common.cmake)
diff --git a/Tests/RunCMake/CMP0106/CMakeLists.txt b/Tests/RunCMake/CMP0106/CMakeLists.txt
new file mode 100644
index 0000000..eafa642
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/CMakeLists.txt
@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.1)
+if (RunCMake_TEST STREQUAL "CMP0106-WARN-VTK")
+  project(VTK NONE)
+else ()
+  project(${RunCMake_TEST} NONE)
+endif ()
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/CMP0106/RunCMakeTest.cmake b/Tests/RunCMake/CMP0106/RunCMakeTest.cmake
new file mode 100644
index 0000000..acec054
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/RunCMakeTest.cmake
@@ -0,0 +1,7 @@
+include(RunCMake)
+
+run_cmake(CMP0106-OLD)
+run_cmake(CMP0106-NEW)
+run_cmake(CMP0106-WARN)
+run_cmake(CMP0106-WARN-VTK)
+run_cmake(CMP0106-WARN-ParaView)
diff --git a/Tests/RunCMake/CMP0106/subdir/CMakeLists.txt b/Tests/RunCMake/CMP0106/subdir/CMakeLists.txt
new file mode 100644
index 0000000..ed1dd05
--- /dev/null
+++ b/Tests/RunCMake/CMP0106/subdir/CMakeLists.txt
@@ -0,0 +1,2 @@
+project(VTK NONE)
+include(${CMAKE_CURRENT_SOURCE_DIR}/../CMP0106-Common.cmake)
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index f5472d9..cc88868 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -119,6 +119,7 @@ add_RunCMake_test(CMP0102)
 if(CMake_TEST_CUDA)
   add_RunCMake_test(CMP0104)
 endif()
+add_RunCMake_test(CMP0106)
 
 # The test for Policy 65 requires the use of the
 # CMAKE_SHARED_LIBRARY_LINK_CXX_FLAGS variable, which both the VS and Xcode