Tutorial: Make code snippets linkable

Extend the change from commit 9e5bbb69 (Tutorial: Add captions for
code blocks, 2021-06-11) to also add a Sphinx named target to code
blocks.  Name each target after the change the code block makes.

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

@@ -8,6 +8,7 @@ required. This will be the starting point for our tutorial. Create a
 
 .. code-block:: cmake
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-start
 
   cmake_minimum_required(VERSION 3.10)
 
@@ -35,6 +36,7 @@ to set the project name and version number.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-project-VERSION
   :language: cmake
   :end-before: # specify the C++ standard
 
@@ -43,6 +45,7 @@ code:
 
 .. literalinclude:: Step2/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-configure_file
   :language: cmake
   :start-after: # to the source code
   :end-before: # add the executable
@@ -53,6 +56,7 @@ files. Add the following lines to the end of the ``CMakeLists.txt`` file:
 
 .. literalinclude:: Step2/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-target_include_directories
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 
@@ -61,6 +65,7 @@ directory with the following contents:
 
 .. literalinclude:: Step2/TutorialConfig.h.in
   :caption: TutorialConfig.h.in
+  :name: TutorialConfig.h.in
   :language: c++
 
 When CMake configures this header file the values for
@@ -75,6 +80,7 @@ Finally, let's print out the executable name and version number by updating
 
 .. literalinclude:: Step2/tutorial.cxx
   :caption: tutorial.cxx
+  :name: tutorial.cxx-print-version
   :language: c++
   :start-after: {
   :end-before: // convert input to double
@@ -88,6 +94,7 @@ Next let's add some C++11 features to our project by replacing ``atof`` with
 
 .. literalinclude:: Step2/tutorial.cxx
   :caption: tutorial.cxx
+  :name: tutorial.cxx-cxx11
   :language: c++
   :start-after: // convert input to double
   :end-before: // calculate square root
@@ -102,6 +109,7 @@ call to ``add_executable``.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-CXX_STANDARD
   :language: cmake
   :end-before: # configure a header file to pass some of the CMake settings
 

Help/guide/tutorial/Adding Export Configuration.rst

@@ -19,6 +19,7 @@ command in ``MathFunctions/CMakeLists.txt`` to look like:
 
 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-install-TARGETS-EXPORT
   :language: cmake
   :start-after: # install rules
 
@@ -28,6 +29,7 @@ adding the following to the bottom of the top-level ``CMakeLists.txt``:
 
 .. literalinclude:: Complete/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-install-EXPORT
   :language: cmake
   :start-after: # install the configuration targets
   :end-before: include(CMakePackageConfigHelpers)
@@ -54,6 +56,7 @@ directory and from an install / package. This means converting the
 
 .. literalinclude:: Step12/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-target_include_directories
   :language: cmake
   :start-after: # to find MathFunctions.h, while we don't.
   :end-before: # should we use our own math functions
@@ -69,12 +72,14 @@ ahead and add a new file to the top-level of the project called
 
 .. literalinclude:: Step12/Config.cmake.in
   :caption: Config.cmake.in
+  :name: 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
+  :name: CMakeLists.txt-install-Config.cmake
   :language: cmake
   :start-after: # install the configuration targets
   :end-before: # generate the export
@@ -86,6 +91,7 @@ the following to the bottom of the top level ``CMakeLists.txt``:
 
 .. literalinclude:: Step12/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-export
   :language: cmake
   :start-after: # needs to be after the install(TARGETS ) command
 

Help/guide/tutorial/Adding Generator Expressions.rst

@@ -39,6 +39,7 @@ So the following code:
 
 .. literalinclude:: Step10/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-CXX_STANDARD-variable-remove
   :language: cmake
   :start-after: project(Tutorial VERSION 1.0)
   :end-before: # control where the static and shared libraries are built so that on windows
@@ -47,6 +48,7 @@ Would be replaced with:
 
 .. literalinclude:: Step11/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-cxx_std-feature
   :language: cmake
   :start-after: project(Tutorial VERSION 1.0)
   :end-before: # add compiler warning flags just when building this project via
@@ -59,6 +61,7 @@ of compiler ids as seen below:
 
 .. literalinclude:: Step11/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-target_compile_options-genex
   :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

@@ -11,6 +11,7 @@ Replace:
 
 .. code-block:: cmake
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-enable_testing-remove
 
   # enable testing
   enable_testing()
@@ -19,6 +20,7 @@ With:
 
 .. code-block:: cmake
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-include-CTest
 
   # enable dashboard scripting
   include(CTest)
@@ -32,6 +34,7 @@ dashboard.
 
 .. literalinclude:: Step9/CTestConfig.cmake
   :caption: CTestConfig.cmake
+  :name: 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

@@ -16,6 +16,7 @@ the ``m`` library. If ``log`` and ``exp`` are not initially found, require the
 
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-check_symbol_exists
   :language: cmake
   :start-after: # does this system provide the log and exp functions?
   :end-before: # add compile definitions
@@ -25,6 +26,7 @@ If available, use :command:`target_compile_definitions` to specify
 
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-target_compile_definitions
   :language: cmake
   :start-after: # add compile definitions
   :end-before: # install rules
@@ -36,6 +38,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
+  :name: MathFunctions/mysqrt.cxx-ifdef
   :language: c++
   :start-after: // if we have both log and exp then use them
   :end-before: // do ten iterations
@@ -44,6 +47,7 @@ We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
+  :name: MathFunctions/mysqrt.cxx-include-cmath
   :language: c++
   :end-before: #include <iostream>
 

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

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

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

@@ -28,6 +28,7 @@ First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable
   :language: cmake
   :start-after: # first we add the executable that generates the table
   :end-before: # add the command to generate the source code
@@ -37,6 +38,7 @@ by running MakeTable.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h
   :language: cmake
   :start-after: # add the command to generate the source code
   :end-before: # add the main library
@@ -47,6 +49,7 @@ of sources for the library MathFunctions.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-add_library-Table.h
   :language: cmake
   :start-after: # add the main library
   :end-before: # state that anybody linking
@@ -56,6 +59,7 @@ directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h
   :language: cmake
   :start-after: # state that we depend on our bin
   :end-before: # install rules
@@ -65,6 +69,7 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
 
 .. literalinclude:: Step7/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
+  :name: MathFunctions/mysqrt.cxx
   :language: c++
   :start-after: // a hack square root calculation using simple operations
 

Help/guide/tutorial/Adding a Library.rst

@@ -17,6 +17,7 @@ directory:
 
 .. literalinclude:: Step3/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt
   :language: cmake
 
 To make use of the new library we will add an :command:`add_subdirectory`
@@ -27,6 +28,7 @@ last few lines of the top-level ``CMakeLists.txt`` file should now look like:
 
 .. code-block:: cmake
         :caption: CMakeLists.txt
+        :name: CMakeLists.txt-add_subdirectory
 
         # add the MathFunctions library
         add_subdirectory(MathFunctions)
@@ -50,6 +52,7 @@ occurrence. The first step is to add an option to the top-level
 
 .. literalinclude:: Step3/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-option
   :language: cmake
   :start-after: # should we use our own math functions
   :end-before: # add the MathFunctions library
@@ -66,6 +69,7 @@ file to look like the following:
 
 .. literalinclude:: Step3/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS
   :language: cmake
   :start-after: # add the MathFunctions library
 
@@ -81,6 +85,7 @@ need it:
 
 .. literalinclude:: Step3/tutorial.cxx
   :caption: tutorial.cxx
+  :name: tutorial.cxx-ifdef-include
   :language: c++
   :start-after: // should we include the MathFunctions header
   :end-before: int main
@@ -90,6 +95,7 @@ function is used:
 
 .. literalinclude:: Step3/tutorial.cxx
   :caption: tutorial.cxx
+  :name: tutorial.cxx-ifdef-const
   :language: c++
   :start-after: // which square root function should we use?
   :end-before: std::cout << "The square root of
@@ -99,6 +105,7 @@ Since the source code now requires ``USE_MYMATH`` we can add it to
 
 .. literalinclude:: Step3/TutorialConfig.h.in
   :caption: TutorialConfig.h.in
+  :name: TutorialConfig.h.in-cmakedefine
   :language: c++
   :lines: 4
 

Help/guide/tutorial/Installing and Testing.rst

@@ -14,6 +14,7 @@ So to the end of ``MathFunctions/CMakeLists.txt`` we add:
 
 .. literalinclude:: Step5/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-install-TARGETS
   :language: cmake
   :start-after: # install rules
 
@@ -21,6 +22,7 @@ And to the end of the top-level ``CMakeLists.txt`` we add:
 
 .. literalinclude:: Step5/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-install-TARGETS
   :language: cmake
   :start-after: # add the install targets
   :end-before: # enable testing
@@ -65,6 +67,7 @@ the application is working correctly.
 
 .. literalinclude:: Step5/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-enable_testing
   :language: cmake
   :start-after: # enable testing
 

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

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

Help/guide/tutorial/Packaging an Installer.rst

@@ -13,6 +13,7 @@ few lines to the bottom of our top-level ``CMakeLists.txt`` file.
 
 .. literalinclude:: Step8/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-include-CPack
   :language: cmake
   :start-after: # setup installer
 

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

@@ -21,6 +21,7 @@ The first step is to update the starting section of the top-level
 
 .. literalinclude:: Step10/CMakeLists.txt
   :caption: CMakeLists.txt
+  :name: CMakeLists.txt-option-BUILD_SHARED_LIBS
   :language: cmake
   :end-before: # add the binary tree
 
@@ -34,6 +35,7 @@ The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-add_library-STATIC
   :language: cmake
   :lines: 1-36,42-
 
@@ -42,6 +44,7 @@ Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
 
 .. literalinclude:: Step10/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
+  :name: MathFunctions/mysqrt.cxx-namespace
   :language: c++
 
 We also need to make some changes in ``tutorial.cxx``, so that it no longer
@@ -55,6 +58,7 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 
 .. literalinclude:: Step10/MathFunctions/MathFunctions.h
   :caption: MathFunctions/MathFunctions.h
+  :name: MathFunctions/MathFunctions.h
   :language: c++
 
 At this point, if you build everything, you may notice that linking fails
@@ -65,6 +69,7 @@ SqrtLibrary to be ``True`` no matter the build type.
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE
   :language: cmake
   :lines: 37-42