Merge topic 'help-guide-tutorial'

8ab8563533 Help: Add tutorial guide table of contents
0a6c9c417a Help: Update tutorial to include text from CMake book
eef3e020c2 Help: Populate tutorial guide text
862cfc0e6c Help/guide/tutorial: Adopt tutorial code
d2fde94809 Help: Add infrastructure for guide-level documentation
f067af8e38 Tests/Tutorial: Remove trailing blank lines
d5a81ef747 Tests/Tutorial: Remove unused file

Acked-by: Kitware Robot <[email protected]>
Merge-request: !3439

CMakeLists.txt

@@ -817,7 +817,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
     PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
                                 GROUP_READ GROUP_EXECUTE
                                 WORLD_READ WORLD_EXECUTE
-    REGEX "Help/dev($|/)" EXCLUDE
+    REGEX "Help/(dev|guide|index.rst)($|/)" EXCLUDE
     )
 
   # Install auxiliary files integrating with other tools.

Tests/Tutorial/Complete/CMakeLists.txt → Help/guide/tutorial/Complete/CMakeLists.txt

@@ -1,20 +1,20 @@
 cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
+set(CMAKE_CXX_STANDARD 14)
+
+# set the version number
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 14)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 if(APPLE)
   set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
 elseif(UNIX)

Tests/Tutorial/MultiPackage/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -62,6 +61,7 @@ target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
 set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
 
+# install rules
 install(TARGETS MathFunctions
         DESTINATION lib
         EXPORT MathFunctionsTargets)

Tests/Tutorial/Step1/TutorialConfig.h.in → Help/guide/tutorial/Step1/TutorialConfig.h.in

@@ -1,4 +1,3 @@
 // the configured options and settings for Tutorial
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
-

Tests/Tutorial/Step11/CMakeLists.txt → Help/guide/tutorial/Step10/CMakeLists.txt

@@ -1,20 +1,20 @@
 cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
+set(CMAKE_CXX_STANDARD 14)
+
+# Set the version number
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 14)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass the version number only
 configure_file(
   "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"

Tests/Tutorial/Step10/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -57,5 +56,6 @@ endif()
 # building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Tests/Tutorial/Step10/tutorial.cxx → Help/guide/tutorial/Step10/tutorial.cxx

@@ -9,6 +9,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;

Tests/Tutorial/Step10/CMakeLists.txt → Help/guide/tutorial/Step11/CMakeLists.txt

@@ -1,20 +1,20 @@
 cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
+set(CMAKE_CXX_STANDARD 14)
+
+# set the version number
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 14)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass the version number only
 configure_file(
   "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"

Tests/Tutorial/Step11/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -56,5 +55,6 @@ target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MY
 #building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Tests/Tutorial/Step11/tutorial.cxx → Help/guide/tutorial/Step11/tutorial.cxx

@@ -9,6 +9,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;

Tests/Tutorial/Step2/CMakeLists.txt → Help/guide/tutorial/Step2/CMakeLists.txt

@@ -2,7 +2,8 @@ cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
-# the version number.
+
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Tests/Tutorial/Step2/TutorialConfig.h.in → Help/guide/tutorial/Step2/TutorialConfig.h.in

@@ -1,4 +1,3 @@
 // the configured options and settings for Tutorial
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
-

Tests/Tutorial/Step2/tutorial.cxx → Help/guide/tutorial/Step2/tutorial.cxx

@@ -8,6 +8,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;

Tests/Tutorial/Step3/CMakeLists.txt → Help/guide/tutorial/Step3/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Tests/Tutorial/Step5/TutorialConfig.h.in → Help/guide/tutorial/Step3/TutorialConfig.h.in

@@ -2,4 +2,3 @@
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
 #cmakedefine USE_MYMATH
-

Tests/Tutorial/Step5/tutorial.cxx → Help/guide/tutorial/Step3/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Tests/Tutorial/Step4/CMakeLists.txt → Help/guide/tutorial/Step4/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Tests/Tutorial/Step3/TutorialConfig.h.in → Help/guide/tutorial/Step4/TutorialConfig.h.in

@@ -2,4 +2,3 @@
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
 #cmakedefine USE_MYMATH
-

Tests/Tutorial/Step6/tutorial.cxx → Help/guide/tutorial/Step4/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Tests/Tutorial/Step5/CMakeLists.txt → Help/guide/tutorial/Step5/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Tests/Tutorial/Step5/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt

@@ -6,5 +6,6 @@ target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Tests/Tutorial/Step4/TutorialConfig.h.in → Help/guide/tutorial/Step5/TutorialConfig.h.in

@@ -2,4 +2,3 @@
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
 #cmakedefine USE_MYMATH
-

Tests/Tutorial/Step4/tutorial.cxx → Help/guide/tutorial/Step5/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Tests/Tutorial/Step6/CMakeLists.txt → Help/guide/tutorial/Step6/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Tests/Tutorial/Step6/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt

@@ -4,11 +4,11 @@ add_library(MathFunctions mysqrt.cxx)
 # to find MathFunctions.h, while we don't.
 # state that we depend on Tutorial_BINARY_DIR but consumers don't, as the
 # TutorialConfig.h include is an implementation detail
-
 target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           PRIVATE ${Tutorial_BINARY_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Tests/Tutorial/Step3/tutorial.cxx → Help/guide/tutorial/Step6/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Tests/Tutorial/Step7/CMakeLists.txt → Help/guide/tutorial/Step7/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Tests/Tutorial/Step8/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt

@@ -25,5 +25,6 @@ target_include_directories(MathFunctions
                   ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Tests/Tutorial/Step7/TutorialConfig.h.in → Help/guide/tutorial/Step7/TutorialConfig.h.in

@@ -6,4 +6,3 @@
 // does the platform provide exp and log functions?
 #cmakedefine HAVE_LOG
 #cmakedefine HAVE_EXP
-

Help/guide/tutorial/Step7/tutorial.cxx

@@ -0,0 +1,35 @@
+// A simple program that computes the square root of a number
+#include <cmath>
+#include <iostream>
+#include <string>
+
+#include "TutorialConfig.h"
+
+// should we include the MathFunctions header?
+#ifdef USE_MYMATH
+#  include "MathFunctions.h"
+#endif
+
+int main(int argc, char* argv[])
+{
+  if (argc < 2) {
+    // report version
+    std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
+              << Tutorial_VERSION_MINOR << std::endl;
+    std::cout << "Usage: " << argv[0] << " number" << std::endl;
+    return 1;
+  }
+
+  double inputValue = std::stod(argv[1]);
+
+  // which square root function should we use?
+#ifdef USE_MYMATH
+  double outputValue = mysqrt(inputValue);
+#else
+  double outputValue = sqrt(inputValue);
+#endif
+
+  std::cout << "The square root of " << inputValue << " is " << outputValue
+            << std::endl;
+  return 0;
+}

Tests/Tutorial/Step8/CMakeLists.txt → Help/guide/tutorial/Step8/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 
@@ -74,6 +74,7 @@ do_test(Tutorial 25 "25 is 5")
 do_test(Tutorial -25 "-25 is [-nan|nan|0]")
 do_test(Tutorial 0.0001 "0.0001 is 0.01")
 
+# setup installer
 include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")

Tests/Tutorial/Step7/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt

@@ -25,5 +25,6 @@ target_include_directories(MathFunctions
                   ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Tests/Tutorial/Step6/TutorialConfig.h.in → Help/guide/tutorial/Step8/TutorialConfig.h.in

@@ -6,4 +6,3 @@
 // does the platform provide exp and log functions?
 #cmakedefine HAVE_LOG
 #cmakedefine HAVE_EXP
-

Help/guide/tutorial/Step8/tutorial.cxx

@@ -0,0 +1,35 @@
+// A simple program that computes the square root of a number
+#include <cmath>
+#include <iostream>
+#include <string>
+
+#include "TutorialConfig.h"
+
+// should we include the MathFunctions header?
+#ifdef USE_MYMATH
+#  include "MathFunctions.h"
+#endif
+
+int main(int argc, char* argv[])
+{
+  if (argc < 2) {
+    // report version
+    std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
+              << Tutorial_VERSION_MINOR << std::endl;
+    std::cout << "Usage: " << argv[0] << " number" << std::endl;
+    return 1;
+  }
+
+  double inputValue = std::stod(argv[1]);
+
+  // which square root function should we use?
+#ifdef USE_MYMATH
+  double outputValue = mysqrt(inputValue);
+#else
+  double outputValue = sqrt(inputValue);
+#endif
+
+  std::cout << "The square root of " << inputValue << " is " << outputValue
+            << std::endl;
+  return 0;
+}

Tests/Tutorial/Step9/CMakeLists.txt → Help/guide/tutorial/Step9/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)