More autodoc cleanup to make it easier for Jayenne to use the same ma…

…cros.

Background

Jayenne and Capsaicin should be able to use a lot of the same cmake macros for
setting up a build system that creates html pages via doxygen.  Attempt to
package some of the build system code in a more reusable way.

Changes:

+ Update formatting for `Copyright` and include this text directly into
  `mainpage.dcc`.
+ Create new file `autodoc_macros.cmake` that defines cmake macros and functions
  that will be used by `autodoc/CMakeLists.txt`.
+ Update `draco_info` so it can create a list of authors suitable for including
  in `mainpage.dcc.`
+ Add `autodoc/html/doxygen.css` to the list of files that will be installed in
  `cmake/draco` and that can be used by other projects.
+ The generated `Draco.tag` file is causing a warning `warning: Duplicate
  anchor HOST_NAME_MAX found` when used by other code projects.  Attempt to
  silence this warning.
+ Increase the max number of dot graph nodes to 500 (was 200).
+ Update the `covdir.cfg` script so it is aware of Jayenne's new directory
  layout.
+ Rename structs A, B --> Apple, Banana in `cxx11example_move_semantics.cc` to
  prevent doxygen from linking the article 'A' to this struct.

Copyright

@@ -3,75 +3,116 @@ DRACO Software:
 Terms and Conditions of Use
 ----------------------------------------
 
-Please read these terms and conditions of use carefully before using
-this software. This code is unclassified and has been assigned LA-CC-16-016.
+Please read these terms and conditions of use carefully before using this
+software. This code is unclassified and has been assigned LA-CC-16-016.
 
 Copyright
 --------------------
 
-Copyright (C) 2016-2018 Los Alamos National Security, LLC.
-All rights reserved.
-
-Copyright 2016.  Los Alamos National Security, LLC. This software was
-produced under U.S. Government contract DE-AC52-06NA25396 for Los
-Alamos National Laboratory (LANL), which is operated by Los Alamos
-National Security, LLC for the U.S. Department of Energy. The
-U.S. Government has rights to use, reproduce, and distribute this
-software.  NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL SECURITY,
-LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY
-FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
-derivative works, such modified software should be clearly marked, so
-as not to confuse it with the version available from LANL.
-
-Additionally, redistribution and use in source and binary forms, with
-or without modification, are permitted provided that the following
-conditions are met:
-
-- Redistributions of source code must retain the above copyright
-  notice, this list of conditions and the following disclaimer.
-
-- Redistributions in binary form must reproduce the above copyright
-  notice, this list of conditions and the following disclaimer in the
-  documentation and/or other materials provided with the distribution.
-
-- Neither the name of Los Alamos National Security, LLC, Los Alamos
-  National Laboratory, LANL, the U.S. Government, nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY LOS ALAMOS NATIONAL SECURITY, LLC AND
-CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
-BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL LOS
-ALAMOS NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY
-DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
-GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
-IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Copyright (C) 2016-2018 Los Alamos National Security, LLC.  All rights reserved.
+
+Copyright 2016.  Los Alamos National Security, LLC. This software was produced
+under U.S. Government contract DE-AC52-06NA25396 for Los Alamos National
+Laboratory (LANL), which is operated by Los Alamos National Security, LLC for
+the U.S. Department of Energy. The U.S. Government has rights to use, reproduce,
+and distribute this software.  NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL
+SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY
+FOR THE USE OF THIS SOFTWARE.  If software is modified to produce derivative
+works, such modified software should be clearly marked, so as not to confuse it
+with the version available from LANL.
+
+Additionally, redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+- Neither the name of Los Alamos National Security, LLC, Los Alamos National
+  Laboratory, LANL, the U.S. Government, nor the names of its contributors may
+  be used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY LOS ALAMOS NATIONAL SECURITY, LLC AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL LOS ALAMOS NATIONAL SECURITY, LLC OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.
 
 
 Additional Copyright Information:
 ----------------------------------------
 
-The Draco software suite links against external libraries.  Copyrights
-to these associated software packages may are listed below:
+The Draco software suite links against external libraries. Copyrights to these
+associated software packages may are listed below:
 
-1. Various MPI implementations (OpenMPI, MPICH, Microsoft MPI, Intel
-   MPI, etc.); https://www.open-mpi.org/community/license.php
+1. Various MPI implementations (OpenMPI, MPICH, Microsoft MPI, Intel MPI, etc.);
+   https://www.open-mpi.org/community/license.php
 
-2. Gnu Scientific Library - GSL is distributed under the terms of the
-   GNU General Public License (GPL) - http://www.gnu.org/software/gsl/
+   An open source Message Passing Interface implementation. The Open MPI Project
+   is an open source Message Passing Interface implementation that is developed
+   and maintained by a consortium of academic, research, and industry
+   partners. Open MPI is therefore able to combine the expertise, technologies,
+   and resources from all across the High Performance Computing community in
+   order to build the best MPI library available.  Open MPI offers advantages
+   for system and software vendors, application developers and computer science
+   researchers.
 
-3. LAPACK - http://www.netlib.org/lapack/LICENSE.txt
-   or package providing this functionality (e.g.: Intel MKL)
+2. Gnu Scientific Library - GSL is distributed under the terms of the GNU
+   General Public License (GPL) - http://www.gnu.org/software/gsl/
+
+   The GNU Scientific Library (GSL) is a numerical library for C and C++
+   programmers. It is free software under the GNU General Public License.  The
+   library provides a wide range of mathematical routines such as random number
+   generators, special functions and least-squares fitting.  There are over 1000
+   functions in total with an extensive test suite.
+
+3. LAPACK - http://www.netlib.org/lapack/LICENSE.txt  (or equivalent)
+
+   LAPACK version 3.X is a comprehensive FORTRAN library that does linear
+   algebra operations including matrix inversions, least squared solutions to
+   linear sets of equations, eigenvector analysis, singular value decomposition,
+   etc. It is a very comprehensive and reputable package that has found
+   extensive use in the scientific community.
 
 4. Random123 -
    https://www.deshawresearch.com/downloads/download_random123.cgi/Random123_License.txt
 
-5. CUDA - http://docs.nvidia.com/cuda/eula/index.html#nvidia-cuda-toolkit-license-agreement
+   Random123 is a library of 'counter-based' random number generators (CBRNGs),
+   in which the Nth random number can be obtained by applying a stateless mixing
+   function to N instead of the conventional approach of using N iterations of a
+   stateful transformation.
+
+5. CUDA -
+   http://docs.nvidia.com/cuda/eula/index.html#nvidia-cuda-toolkit-license-agreement
 
 6. Qt - GNU Lesser General Public License (LGPL) version 3,
    http://doc.qt.io/qt-5/opensourcelicense.html
+
+7. Metis - http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
+
+   METIS is a set of serial programs for partitioning graphs, partitioning
+   finite element meshes, and producing fill reducing orderings for sparse
+   matrices. The algorithms implemented in METIS are based on the multilevel
+   recursive-bisection, multilevel k-way, and multi-constraint partitioning
+   schemes.
+
+8. ParMetis - http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview
+
+   ParMETIS is an MPI-based parallel library that implements a variety of
+   algorithms for partitioning unstructured graphs, meshes, and for computing
+   fill-reducing orderings of sparse matrices.
+
+9. SuperLU-DIST - http://crd-legacy.lbl.gov/~xiaoye/SuperLU/
+
+   A general purpose library for the direct solution of large, sparse,
+   nonsymmetric systems of linear equations on high performance machines.

autodoc/CMakeLists.txt

@@ -19,64 +19,19 @@ if( NOT DOXYGEN_FOUND )
   return()
 endif()
 
- # if AUTODOCDIR is set in environment (or make command line), create a CMake
- # variable with this value.
- if( ENV{AUTODOCDIR} )
-    set( AUTODOCDIR "$ENV{AUTODOCDIR}" )
- endif()
- # if AUTODOCDIR is set, use it, otherwise, default to CMAKE_INSTALL_PREFIX.
- if( AUTODOCDIR )
-    set( DOXYGEN_OUTPUT_DIR "${AUTODOCDIR}" )
-  else()
-    set( DOXYGEN_OUTPUT_DIR ${CMAKE_INSTALL_PREFIX}/autodoc )
- endif()
+include(autodoc_macros)
+set_autodocdir() # --> AUTODOCDIR
 
 # Source directories that should be examined by doxygen Sets ${DOXYGEN_INPUT}.
 # This value is embedded in the doxygen_config file below.
-set( DOXYGEN_INPUT
-   "${PROJECT_SOURCE_DIR}/autodoc ${PROJECT_BINARY_DIR}/autodoc" )
-
-# BUG: Move this list generation into component_macros.cmake so that inactive 
-#      packages are not included in this list.
-file( GLOB package_list ${PROJECT_SOURCE_DIR}/src/* )
-foreach( package ${package_list} )
-   if( EXISTS ${package}/CMakeLists.txt )
-      set( DOXYGEN_INPUT "${DOXYGEN_INPUT} ${package}" )
-   endif()
-   if( EXISTS ${package}/test/CMakeLists.txt )
-      set( DOXYGEN_INPUT "${DOXYGEN_INPUT} ${package}/test" )
-      set( DOXYGEN_EXAMPLES "${DOXYGEN_EXAMPLES} ${package}/test" )
-   endif()
-   if( EXISTS ${package}/autodoc )
-      set( DOXYGEN_INPUT "${DOXYGEN_INPUT} ${package}/autodoc" )
-   endif()
-endforeach()
-
-# Tell doxygen where image files are located so they can be copied to the 
+set_doxygen_input() # --> DOXYGEN_INPUT
+
+# Tell doxygen where image files are located so they can be copied to the
 # output directory.
-#
-# The list of source files (this variable also set by 
-# comonent_macros.cmake::process_autodoc_pages()
-list(APPEND DOXYGEN_IMAGE_PATH 
-  "${PROJECT_SOURCE_DIR}/autodoc"
-  "${PROJECT_SOURCE_DIR}/autodoc/html" )
-list( REMOVE_DUPLICATES DOXYGEN_IMAGE_PATH )
-# convert list of image directories into a space delimited string
-unset( temp )
-foreach( image_dir ${DOXYGEN_IMAGE_PATH} )
-   set( temp "${temp} ${image_dir}" )
-endforeach()
-set( DOXYGEN_IMAGE_PATH "${temp}" )
-unset( temp )
-
-# Also look for files that have been configured (.in files) and
-# placed in the BINARY_DIR.
-file( GLOB package_list ${PROJECT_BINARY_DIR}/src/* )
-foreach( package ${package_list} )
-   if( EXISTS ${package}/autodoc )
-      set( DOXYGEN_INPUT "${DOXYGEN_INPUT} ${package}/autodoc" )
-   endif()
-endforeach()
+set_doxygen_image_path() # --> DOXYGEN_IMAGE_PATH
+
+# Doxygen only allows 32 threads max
+set_doxygen_dot_num_threads() # --> DOXYGEN_DOT_NUM_THREADS
 
 set( DOXYGEN_HTML_OUTPUT draco )
 set( project_brief "Object-oriented components for numerically intensive, parallel, radiation transport applications.")
@@ -108,37 +63,28 @@ add_custom_command(
           -Dhtmlheader="${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/header.html"
           -Dhtmlfooter="${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/footer.html"
           -Dproject_logo="${PROJECT_SOURCE_DIR}/autodoc/html/dragon.jpg"
-          -Dnumthreads=${MPIEXEC_MAX_NUMPROCS}
+          -Dnumthreads=${DOXYGEN_DOT_NUM_THREADS}
           -DDOXYGEN_IMAGE_PATH=${DOXYGEN_IMAGE_PATH}
           -P "${PROJECT_SOURCE_DIR}/config/configureFileOnMake.cmake"
-  DEPENDS "${PROJECT_SOURCE_DIR}/config/doxygen_config.in" 
+  DEPENDS "${PROJECT_SOURCE_DIR}/config/doxygen_config.in"
   WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/autodoc)
-configure_file(
-  "${PROJECT_SOURCE_DIR}/autodoc/html/footer.html.in"
-  "${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/footer.html"
-  @ONLY )
-configure_file(
-  "${PROJECT_SOURCE_DIR}/autodoc/html/header.html.in"
-  "${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/header.html"
-  @ONLY )
-add_custom_command(
-  OUTPUT  "${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/doxygen.css"
-  COMMAND "${CMAKE_COMMAND}"
-          -DINFILE="${PROJECT_SOURCE_DIR}/autodoc/html/doxygen.css"
-          -DOUTFILE="${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/doxygen.css"
-          -P "${PROJECT_SOURCE_DIR}/config/configureFileOnMake.cmake"
-  DEPENDS "${PROJECT_SOURCE_DIR}/autodoc/html/doxygen.css" )
+
+# Create header.html, footer.html and doxygen.css.
+doxygen_provide_support_files()
+
 add_custom_command(
   OUTPUT  "${PROJECT_BINARY_DIR}/autodoc/mainpage.dcc"
   COMMAND "${CMAKE_COMMAND}"
           -DINFILE="${PROJECT_SOURCE_DIR}/autodoc/mainpage.dcc.in"
           -DOUTFILE="${PROJECT_BINARY_DIR}/autodoc/mainpage.dcc"
           -DCOMP_LINKS=${COMP_LINKS}
           -DPACKAGE_LINKS=${PACKAGE_LINKS}
-          -P "${PROJECT_SOURCE_DIR}/config/configureFileOnMake.cmake"
+          -DDraco_VERSION_FULL="${Draco_VERSION_FULL}"
+          -DDRACO_INFO="$<TARGET_FILE_DIR:Exe_draco_info>/$<TARGET_FILE_NAME:Exe_draco_info>"
+          -DPROJECT_SOURCE_DIR="${PROJECT_SOURCE_DIR}"
+          -P "${PROJECT_SOURCE_DIR}/autodoc//generate_mainpage_dcc.cmake"
   DEPENDS "${PROJECT_SOURCE_DIR}/autodoc/mainpage.dcc.in"
-  COMMENT "Doxygen docs are installed at"
-          "${DOXYGEN_HTML_OUTPUT}.  " )
+          Exe_draco_info )
 add_custom_command(
   OUTPUT  "${PROJECT_BINARY_DIR}/autodoc/build_system.dcc"
   COMMAND "${CMAKE_COMMAND}"
@@ -147,7 +93,7 @@ add_custom_command(
           -DCOMP_LINKS=${COMP_LINKS}
           -DPACKAGE_LINKS=${PACKAGE_LINKS}
           -P "${PROJECT_SOURCE_DIR}/config/configureFileOnMake.cmake"
-  DEPENDS "${PROJECT_SOURCE_DIR}/autodoc/build_system.dcc.in" )          
+  DEPENDS "${PROJECT_SOURCE_DIR}/autodoc/build_system.dcc.in" )
 
 # The actual doxygen command that will be run
 add_custom_command(
@@ -174,5 +120,7 @@ add_custom_target( autodoc
 
 # To Do:
 # 1. How to 'make clean'?
-# 2. Consider using tagfiles and building each component as an thread
-#    to decrease wall clock time needed to build docs.
+
+#------------------------------------------------------------------------------#
+# End autodoc/CMakeLists.txt
+#------------------------------------------------------------------------------#