Tutorial: Add captions for code blocks

Help/guide/tutorial/A Basic Starting Point.rst

@@ -7,6 +7,7 @@ required. This will be the starting point for our tutorial. Create a
 ``CMakeLists.txt`` file in the ``Step1`` directory that looks like:
 
 .. code-block:: cmake
+  :caption: CMakeLists.txt
 
   cmake_minimum_required(VERSION 3.10)
 
@@ -33,6 +34,7 @@ First, modify the ``CMakeLists.txt`` file to use the :command:`project` command
 to set the project name and version number.
 
 .. literalinclude:: Step2/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :end-before: # specify the C++ standard
 
@@ -40,6 +42,7 @@ Then, configure a header file to pass the version number to the source
 code:
 
 .. literalinclude:: Step2/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # to the source code
   :end-before: # add the executable
@@ -49,6 +52,7 @@ must add that directory to the list of paths to search for include
 files. Add the following lines to the end of the ``CMakeLists.txt`` file:
 
 .. literalinclude:: Step2/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 
@@ -56,6 +60,7 @@ Using your favorite editor, create ``TutorialConfig.h.in`` in the source
 directory with the following contents:
 
 .. literalinclude:: Step2/TutorialConfig.h.in
+  :caption: TutorialConfig.h.in
   :language: c++
 
 When CMake configures this header file the values for
@@ -69,6 +74,7 @@ Finally, let's print out the executable name and version number by updating
 ``tutorial.cxx`` as follows:
 
 .. literalinclude:: Step2/tutorial.cxx
+  :caption: tutorial.cxx
   :language: c++
   :start-after: {
   :end-before: // convert input to double
@@ -81,6 +87,7 @@ Next let's add some C++11 features to our project by replacing ``atof`` with
 ``#include <cstdlib>``.
 
 .. literalinclude:: Step2/tutorial.cxx
+  :caption: tutorial.cxx
   :language: c++
   :start-after: // convert input to double
   :end-before: // calculate square root
@@ -94,6 +101,7 @@ to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the
 call to ``add_executable``.
 
 .. literalinclude:: Step2/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :end-before: # configure a header file to pass some of the CMake settings
 

Help/guide/tutorial/Adding Export Configuration.rst

@@ -18,6 +18,7 @@ explicitly ``EXPORT`` the ``MathFunctions`` library by updating the ``install``
 command in ``MathFunctions/CMakeLists.txt`` to look like:
 
 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # install rules
 
@@ -26,6 +27,7 @@ install the generated ``MathFunctionsTargets.cmake`` file. This is done by
 adding the following to the bottom of the top-level ``CMakeLists.txt``:
 
 .. literalinclude:: Complete/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # install the configuration targets
   :end-before: include(CMakePackageConfigHelpers)
@@ -51,6 +53,7 @@ directory and from an install / package. This means converting the
 :command:`target_include_directories` call for ``MathFunctions`` to look like:
 
 .. literalinclude:: Step12/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # to find MathFunctions.h, while we don't.
   :end-before: # should we use our own math functions
@@ -65,11 +68,13 @@ ahead and add a new file to the top-level of the project called
 ``Config.cmake.in`` with the following contents:
 
 .. literalinclude:: Step12/Config.cmake.in
+  :caption: Config.cmake.in
 
 Then, to properly configure and install that file, add the following to the
 bottom of the top-level ``CMakeLists.txt``:
 
 .. literalinclude:: Step12/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # install the configuration targets
   :end-before: # generate the export
@@ -80,6 +85,7 @@ we want our project to also be used from a build directory we only have to add
 the following to the bottom of the top level ``CMakeLists.txt``:
 
 .. literalinclude:: Step12/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # needs to be after the install(TARGETS ) command
 

Help/guide/tutorial/Adding Generator Expressions.rst

@@ -38,6 +38,7 @@ instead of using :variable:`CMAKE_CXX_STANDARD`.
 So the following code:
 
 .. literalinclude:: Step10/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: project(Tutorial VERSION 1.0)
   :end-before: # control where the static and shared libraries are built so that on windows
@@ -45,6 +46,7 @@ So the following code:
 Would be replaced with:
 
 .. literalinclude:: Step11/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: project(Tutorial VERSION 1.0)
   :end-before: # add compiler warning flags just when building this project via
@@ -56,6 +58,7 @@ generator expression to control which flags to apply given a language and a set
 of compiler ids as seen below:
 
 .. literalinclude:: Step11/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # the BUILD_INTERFACE genex
   :end-before: # control where the static and shared libraries are built so that on windows

Help/guide/tutorial/Adding Support for a Testing Dashboard.rst

@@ -10,6 +10,7 @@ we include the :module:`CTest` module in our top-level ``CMakeLists.txt``.
 Replace:
 
 .. code-block:: cmake
+  :caption: CMakeLists.txt
 
   # enable testing
   enable_testing()
@@ -17,6 +18,7 @@ Replace:
 With:
 
 .. code-block:: cmake
+  :caption: CMakeLists.txt
 
   # enable dashboard scripting
   include(CTest)
@@ -29,6 +31,7 @@ directory where we can specify the name of the project and where to submit the
 dashboard.
 
 .. literalinclude:: Step9/CTestConfig.cmake
+  :caption: CTestConfig.cmake
   :language: cmake
 
 The :manual:`ctest <ctest(1)>` executable will read in this file when it runs.

Help/guide/tutorial/Adding System Introspection.rst

@@ -15,6 +15,7 @@ the ``m`` library. If ``log`` and ``exp`` are not initially found, require the
 ``m`` library and try again.
 
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # does this system provide the log and exp functions?
   :end-before: # add compile definitions
@@ -23,6 +24,7 @@ If available, use :command:`target_compile_definitions` to specify
 ``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions.
 
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # add compile definitions
   :end-before: # install rules
@@ -33,6 +35,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 ``#endif`` before returning the result!):
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+  :caption: MathFunctions/mysqrt.cxx
   :language: c++
   :start-after: // if we have both log and exp then use them
   :end-before: // do ten iterations
@@ -40,6 +43,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+  :caption: MathFunctions/mysqrt.cxx
   :language: c++
   :end-before: #include <iostream>
 

Help/guide/tutorial/Adding Usage Requirements for a Library.rst

@@ -22,6 +22,7 @@ doesn't. Add the following lines to the end of
 ``MathFunctions/CMakeLists.txt``:
 
 .. literalinclude:: Step4/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # to find MathFunctions.h
 
@@ -30,6 +31,7 @@ remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
 ``CMakeLists.txt``, here:
 
 .. literalinclude:: Step4/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # add the MathFunctions library
   :end-before: # add the executable
@@ -37,6 +39,7 @@ remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
 And here:
 
 .. literalinclude:: Step4/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 

Help/guide/tutorial/Adding a Custom Command and Generated File.rst

@@ -27,6 +27,7 @@ First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
 ``MakeTable`` is added as any other executable would be added.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # first we add the executable that generates the table
   :end-before: # add the command to generate the source code
@@ -35,6 +36,7 @@ Then we add a custom command that specifies how to produce ``Table.h``
 by running MakeTable.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # add the command to generate the source code
   :end-before: # add the main library
@@ -44,6 +46,7 @@ file ``Table.h``. This is done by adding the generated ``Table.h`` to the list
 of sources for the library MathFunctions.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # add the main library
   :end-before: # state that anybody linking
@@ -52,6 +55,7 @@ We also have to add the current binary directory to the list of include
 directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # state that we depend on our bin
   :end-before: # install rules
@@ -60,6 +64,7 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
 ``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table:
 
 .. literalinclude:: Step7/MathFunctions/mysqrt.cxx
+  :caption: MathFunctions/mysqrt.cxx
   :language: c++
   :start-after: // a hack square root calculation using simple operations
 

Help/guide/tutorial/Adding a Library.rst

@@ -16,6 +16,7 @@ Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions``
 directory:
 
 .. literalinclude:: Step3/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
 
 To make use of the new library we will add an :command:`add_subdirectory`
@@ -25,6 +26,7 @@ an include directory so that the ``mysqrt.h`` header file can be found. The
 last few lines of the top-level ``CMakeLists.txt`` file should now look like:
 
 .. code-block:: cmake
+        :caption: CMakeLists.txt
 
         # add the MathFunctions library
         add_subdirectory(MathFunctions)
@@ -47,6 +49,7 @@ occurrence. The first step is to add an option to the top-level
 ``CMakeLists.txt`` file.
 
 .. literalinclude:: Step3/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # should we use our own math functions
   :end-before: # add the MathFunctions library
@@ -62,6 +65,7 @@ conditional. To do this we change the end of the top-level ``CMakeLists.txt``
 file to look like the following:
 
 .. literalinclude:: Step3/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # add the MathFunctions library
 
@@ -76,6 +80,7 @@ First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we
 need it:
 
 .. literalinclude:: Step3/tutorial.cxx
+  :caption: tutorial.cxx
   :language: c++
   :start-after: // should we include the MathFunctions header
   :end-before: int main
@@ -84,6 +89,7 @@ Then, in the same file, make ``USE_MYMATH`` control which square root
 function is used:
 
 .. literalinclude:: Step3/tutorial.cxx
+  :caption: tutorial.cxx
   :language: c++
   :start-after: // which square root function should we use?
   :end-before: std::cout << "The square root of
@@ -92,6 +98,7 @@ Since the source code now requires ``USE_MYMATH`` we can add it to
 ``TutorialConfig.h.in`` with the following line:
 
 .. literalinclude:: Step3/TutorialConfig.h.in
+  :caption: TutorialConfig.h.in
   :language: c++
   :lines: 4
 

Help/guide/tutorial/Installing and Testing.rst

@@ -13,12 +13,14 @@ executable and configured header.
 So to the end of ``MathFunctions/CMakeLists.txt`` we add:
 
 .. literalinclude:: Step5/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # install rules
 
 And to the end of the top-level ``CMakeLists.txt`` we add:
 
 .. literalinclude:: Step5/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # add the install targets
   :end-before: # enable testing
@@ -62,6 +64,7 @@ file we can enable testing and then add a number of basic tests to verify that
 the application is working correctly.
 
 .. literalinclude:: Step5/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # enable testing
 

Help/guide/tutorial/Packaging Debug and Release.rst

@@ -17,6 +17,7 @@ Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
 ``CMakeLists.txt`` file:
 
 .. literalinclude:: Complete/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: project(Tutorial VERSION 1.0)
   :end-before: target_compile_features(tutorial_compiler_flags
@@ -24,6 +25,7 @@ Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
 And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable:
 
 .. literalinclude:: Complete/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # add the executable
   :end-before: # add the binary tree to the search path for include files
@@ -33,6 +35,7 @@ Let's also add version numbering to the ``MathFunctions`` library. In
 :prop_tgt:`SOVERSION` properties:
 
 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # setup the version numbering
   :end-before: # install rules
@@ -68,6 +71,7 @@ Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which
 projects to install. In this case, we want to install both debug and release.
 
 .. literalinclude:: Complete/MultiCPackConfig.cmake
+  :caption: MultiCPackConfig.cmake
   :language: cmake
 
 From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our

Help/guide/tutorial/Packaging an Installer.rst

@@ -12,6 +12,7 @@ CPack to create platform specific installers. Specifically we need to add a
 few lines to the bottom of our top-level ``CMakeLists.txt`` file.
 
 .. literalinclude:: Step8/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :start-after: # setup installer
 

Help/guide/tutorial/Selecting Static or Shared Libraries.rst

@@ -20,6 +20,7 @@ The first step is to update the starting section of the top-level
 ``CMakeLists.txt`` to look like:
 
 .. literalinclude:: Step10/CMakeLists.txt
+  :caption: CMakeLists.txt
   :language: cmake
   :end-before: # add the binary tree
 
@@ -32,6 +33,7 @@ explicitly require that SqrtLibrary is built statically.
 The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :lines: 1-36,42-
 
@@ -39,6 +41,7 @@ Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
 ``detail`` namespaces:
 
 .. literalinclude:: Step10/MathFunctions/mysqrt.cxx
+  :caption: MathFunctions/mysqrt.cxx
   :language: c++
 
 We also need to make some changes in ``tutorial.cxx``, so that it no longer
@@ -51,6 +54,7 @@ uses ``USE_MYMATH``:
 Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 
 .. literalinclude:: Step10/MathFunctions/MathFunctions.h
+  :caption: MathFunctions/MathFunctions.h
   :language: c++
 
 At this point, if you build everything, you may notice that linking fails
@@ -60,6 +64,7 @@ explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
 SqrtLibrary to be ``True`` no matter the build type.
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
   :language: cmake
   :lines: 37-42