Merge branch '63-merge-tpls-packages-3' (#63)

Just some documentation updates.

tribits/core/package_arch/TribitsProcessPackagesAndDirsLists.cmake

@@ -381,20 +381,22 @@ endfunction()
 #   ${PROJECT_NAME}_REVERSE_PACKAGES
 #
 # For each of the listed top-level (parent) packages ${PACKAGE_NAME}, it also
-# sets up constant variables like:
+# sets up constant variables defined in `TriBITS Package Top-Level Local
+# Variables`_ like:
 #
 # * `${PACKAGE_NAME}_SOURCE_DIR`_
 # * `${PACKAGE_NAME}_REL_SOURCE_DIR`_
 # * `${PACKAGE_NAME}_TESTGROUP`_
 #
-# and sets up some standard enable/diable vars with default values like:
+# and sets up some standard enable/diable vars with default values as defined
+# in `TriBITS Package Cache Variables`_ like::
 #
 #   ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}
 #
-# NOTE: Set TRIBITS_PROCESS_PACKAGES_AND_DIRS_LISTS_VERBOSE=TRUE to see really
-# verbose debug ouptut from this macro.
+# NOTE: Set ``TRIBITS_PROCESS_PACKAGES_AND_DIRS_LISTS_VERBOSE=TRUE`` to see
+# really verbose debug ouptut from this macro.
 #
-# See `Function call tree for constructing package dependency graph`_
+# See `Function call tree for constructing package dependency graph`_.
 #
 macro(tribits_process_packages_and_dirs_lists  REPOSITORY_NAME  REPOSITORY_DIR)
 

tribits/core/package_arch/TribitsReadAllProjectDepsFilesCreateDepsGraph.cmake

@@ -59,10 +59,16 @@ include(TimingUtils)
 # and TPLs and creates the packages dependency graph.
 #
 # On output, this creates all of the package lists and dependency
-# data-structures described in `TriBITS System Data Structures and
-# Functions`_.
+# data-structures described in the section `TriBITS System Data Structures`_
+# and more specifically the sections:
 #
-# See `Function call tree for constructing package dependency graph`_
+# * `Lists of external and internal packages`_
+# * `List variables defining the package dependencies graph`_
+# * `TriBITS Package Top-Level Local Variables`_
+# * `TriBITS Subpackage Top-Level Local Variables`_
+# * `TriBITS Package Cache Variables`_
+#
+# See `Function call tree for constructing package dependency graph`_.
 #
 macro(tribits_read_all_project_deps_files_create_deps_graph)
 

tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst

@@ -1,5 +1,5 @@
-TriBITS System Data Structures and Functions
---------------------------------------------
+TriBITS System Data Structures
+------------------------------
 
 This section describes the global CMake variables that make up the
 data-structures and the functions that create them that define the TriBITS
@@ -10,6 +10,13 @@ graph of external packages (i.e. TPLs) and internal packages (i.e. buildable
 CMake packages).  This information is meant for maintainers of the TriBITS
 system itself and should not need to be known by TriBITS Project maintainers.
 
+In addition to the variables listed below are the variables documented in:
+
+* `TriBITS Project Core Variables`_
+* `TriBITS Repository Core Variables`_
+* `TriBITS Package Core Variables`_
+* `TriBITS Subpackage Core Variables`_
+
 
 Lists of external and internal packages
 +++++++++++++++++++++++++++++++++++++++

tribits/doc/developers_guide/TribitsDevelopersGuide.rst

@@ -1748,7 +1748,7 @@ A packages' core variables are broken down into the following categories:
 
 .. _TriBITS Package Local Variables:
 
-The following locally scoped *TriBITS Package Local Variables* are defined
+The following locally scoped **TriBITS Package Local Variables** are defined
 when the files for a given TriBITS Package (or any SE package for that matter)
 are being processed:
 
@@ -1777,7 +1777,7 @@ are being processed:
 .. _TriBITS Package Top-Level Local Variables:
 
 Once all of the TriBITS SE package's ``Dependencies.cmake`` files have been
-processed, the following *TriBITS Package Top-Level Local Variables* are
+processed, the following **TriBITS Package Top-Level Local Variables** are
 defined:
 
   .. _${PACKAGE_NAME}_SOURCE_DIR:
@@ -1830,7 +1830,7 @@ defined:
 
 .. _TriBITS Package Cache Variables:
 
-In addition, the following user-settable *TriBITS Package Cache Variables* are
+In addition, the following user-settable **TriBITS Package Cache Variables** are
 defined before a (SE) Package's ``CMakeLists.txt`` file is processed:
 
   .. _${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}:
@@ -1897,7 +1897,7 @@ Logic`_.
 
 .. _TriBITS Package Optional Dependency Macro Variables:
 
-The following local *TriBITS Package Optional Dependency Macro Variables* are
+The following local **TriBITS Package Optional Dependency Macro Variables** are
 defined in the top-level project scope before a (SE) Package's
 ``CMakeLists.txt`` file is processed:
 
@@ -2126,17 +2126,19 @@ TriBITS Subpackage Core Variables
 .................................
 
 The core variables associated with a subpackage are identical to the `TriBITS
-Package Core Variables`_.  The only difference is that a subpackage may need
-to refer to its parent package where a top-level package does not have a
-parent package.  The extra variables that are defined when processing a
-subpackage's files are:
+Package Core Variables`_.  In addition, a subpackage may need to refer to its
+top-level parent package where a top-level package does not have a parent
+package.  These additional variables that are defined for subpackages are
+broken down into the following categories:
 
-  .. _${PACKAGE_NAME}_PARENT_PACKAGE:
+* `TriBITS Subpackage Local Variables`_
+* `TriBITS Subpackage Top-Level Local Variables`_
 
-  ``${PACKAGE_NAME}_PARENT_PACKAGE``
+.. _TriBITS Subpackage Local Variables:
 
-    The name of the parent package.  (NOTE: If this is empty "", then
-    ``${PACKAGE_NAME}`` is actually a parent package and not a subpackage.)
+In addition to the `TriBITS Package Local Variables`_, the following locally
+scoped **TriBITS Subpackage Local Variables** are defined when the files for a
+given TriBITS Subpackage are being processed:
 
   .. _PARENT_PACKAGE_NAME:
 
@@ -2153,6 +2155,20 @@ subpackage's files are:
     The absolute path to the parent package's base binary directory.
 
 
+.. _TriBITS Subpackage Top-Level Local Variables:
+
+In addition to the `TriBITS Package Top-Level Local Variables`_, once all of a
+TriBITS subpackage's ``Dependencies.cmake`` files have been processed, the
+following **TriBITS Subpackage Top-Level Local Variables** are defined:
+
+  .. _${PACKAGE_NAME}_PARENT_PACKAGE:
+
+  ``${PACKAGE_NAME}_PARENT_PACKAGE``
+
+    The name of the parent package.  (NOTE: If this is empty "", then
+    ``${PACKAGE_NAME}`` is actually a parent package and not a subpackage.)
+
+
 How is a TriBITS Subpackage different from a TriBITS Package?
 .............................................................