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.

autodoc/generate_mainpage_dcc.cmake

@@ -0,0 +1,109 @@
+#-----------------------------*-cmake-*----------------------------------------#
+# file   draco/autodoc/generate_mainpage_dcc.cmake
+# author Kelly Thompson <kgt@lanl.gov>
+# date   2010 Oct 14
+# brief  Generate mainpage.dcc during 'make autodoc'
+# note   Copyright (C) 2018 Los Alamos National Security, LLC.
+#        All rights reserved.
+#------------------------------------------------------------------------------#
+
+# Use:
+#   cmake -DINFILE=$infile -DOUTFILE=$outfile -DSUBST_VARIABLE=VALUE ... \
+#         -P generate_mainpage_dcc.cmake
+#
+# Prerequisits:
+# - INFILE must be a valid file (e.g. mainpage.dcc.in)
+#
+# Post
+# - OUTFILE will be written (or overwritten).
+#
+# Suggested use is to generate binary directory files based on build-time
+# changes to corresonding source tree .in file. For example,
+#   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/generate_mainpage_dcc.cmake"
+#    DEPENDS "${PROJECT_SOURCE_DIR}/autodoc/mainpage.dcc.in"
+#  )
+#
+# add_custom_target( mytarget
+#   DEPENDS "${PROJECT_BINARY_DIR}/autodoc/mainpage.dcc"
+#    COMMENT "Building Doxygen mainpage.dcc (HTML)..."
+#    )
+
+if( NOT EXISTS ${INFILE} )
+  message( FATAL_ERROR "
+INFILE and OUTFILE must be set on command line.  For example,
+${CMAKE_COMMAND}
+  -DINFILE=${INFILE}
+  -DOUTFILE=${OUTFILE}
+  -DPROJECT_NAME=${PROJECT_NAME}
+  -DPROJECT_NUMBER=${PROJECT_NUMBER}
+  -DOUTPUT_DIRECTORY=${OUTPUT_DIRECTORY}
+  -DINPUT=${INPUT}
+  -DEXAMPLE_PATH=${EXAMPLE_PATH}
+  -DHTML_OUTPUT=${HTML_OUTPUT}
+  -DTAGFILES=${TAGFILES}
+  -DDOTFILE_DIRS=${DOTFILE_DIRS}
+  -P${PROJECT_SOURCE_DIR}/config/generate_mainpage_dcc.cmake
+" )
+endif()
+
+# Decode "---" as " " for variables passed to this function
+string( REPLACE "___" " " project_brief "${project_brief}" )
+
+# Ensure we use native path styles
+file( TO_NATIVE_PATH "${PROJECT_SOURCE_DIR}" PROJECT_SOURCE_DIR )
+file( TO_NATIVE_PATH "${INFILE}" INFILE )
+file( TO_NATIVE_PATH "${OUTFILE}" OUTFILE )
+file( TO_NATIVE_PATH "${OUTPUT_DIRECTORY}" OUTPUT_DIRECTORY )
+file( TO_NATIVE_PATH "${EXAMPLE_PATH}" EXAMPLE_PATH )
+file( TO_NATIVE_PATH "${HTML_OUTPUT}" HTML_OUTPUT )
+file( TO_NATIVE_PATH "${DOTFILE_DIRS}" DOTFILE_DIRS )
+file( TO_NATIVE_PATH "${DRACO_DIR}" DRACO_DIR )
+# INPUT is a list of paths
+#message("INPUT = ${INPUT}")
+#string( REGEX REPLACE "[ ]" ";" INPUT ${INPUT} )
+#message("INPUT = ${INPUT}")
+#foreach( item ${INPUT} )
+#   file( TO_NATIVE_PATH "${item}" input_path )
+#   set( tmp_input "${tmp_input} ${input_path}" )
+#   message("
+#${item} --> ${tmp_input}
+#INPUT = ${input_path}
+#")
+#endforeach()
+#set( INPUT ${tmp_input} )
+# TAGFILES is a list of paths
+if( TAGFILES )
+   string( REGEX REPLACE "([ ])" ";" list ${TAGFILES} )
+   foreach( item ${list} )
+      file( TO_NATIVE_PATH "${item}" input_path )
+      if( ${input_path} MATCHES ".tag" )
+         set( tmp_tagfiles "${tmp_tagfiles} ${input_path}" )
+      else()
+         set( tmp_tagfiles "${tmp_tagfiles}=${input_path}" )
+      endif()
+   endforeach()
+   set( TAGFILES ${tmp_tagfiles} )
+endif()
+
+# Generate an author list
+
+if( EXISTS "${DRACO_INFO}" )
+  execute_process(
+    COMMAND         "${DRACO_INFO}" -a -d
+    OUTPUT_VARIABLE AUTHOR_LIST )
+endif()
+
+# Generage the new file while updating all of the build-spaecific '@' data.
+
+configure_file( ${INFILE} ${OUTFILE} @ONLY )
+
+#------------------------------------------------------------------------------#
+# End generate_mainpage_dcc.cmake
+#------------------------------------------------------------------------------#

config/autodoc_macros.cmake

@@ -0,0 +1,170 @@
+#-----------------------------*-cmake-*----------------------------------------#
+# file   config/autodoc_macros.cmake
+# author Kelly G. Thompson, kgt@lanl.gov
+# date   Wednesday, Nov 14, 2018, 19:01 pm
+# brief  Provide extra macros to simplify CMakeLists.txt for autodoc
+#        directories.
+# note   Copyright (C) 2018 Los Alamos National Security, LLC.
+#        All rights reserved.
+#------------------------------------------------------------------------------#
+
+set(draco_config_dir ${CMAKE_CURRENT_LIST_DIR} CACHE INTERNAL "")
+
+#------------------------------------------------------------------------------
+# Set the target directory where the html files wll be created.
+#------------------------------------------------------------------------------
+function( set_autodocdir )
+  # 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}" PARENT_SCOPE)
+  else()
+    set( DOXYGEN_OUTPUT_DIR ${CMAKE_INSTALL_PREFIX}/autodoc PARENT_SCOPE)
+  endif()
+
+endfunction()
+
+#------------------------------------------------------------------------------
+# Build a list of directories that include sources that doxygen should examine.
+#------------------------------------------------------------------------------
+function( set_doxygen_input )
+
+  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 )
+      list( APPEND DOXYGEN_INPUT "${package}" )
+    endif()
+    if( EXISTS ${package}/test/CMakeLists.txt )
+      list( APPEND DOXYGEN_INPUT "${package}/test" )
+      set( DOXYGEN_EXAMPLES "${DOXYGEN_EXAMPLES} ${package}/test" )
+    endif()
+    if( EXISTS ${package}/autodoc )
+      list( APPEND DOXYGEN_INPUT "${package}/autodoc" )
+    endif()
+  endforeach()
+
+  # 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} )
+    # pick up processed .dcc files
+    if( EXISTS ${package}/autodoc )
+      list( APPEND DOXYGEN_INPUT "${package}/autodoc" )
+    endif()
+  endforeach()
+
+  # convert list of image directories into a space delimited string
+  unset( temp )
+  foreach( dir ${DOXYGEN_INPUT} )
+    set( temp "${temp} ${dir}" )
+  endforeach()
+  set( DOXYGEN_INPUT "${temp}" PARENT_SCOPE)
+  unset( temp )
+
+endfunction()
+
+#------------------------------------------------------------------------------
+# Build a list of directories that include images that doxygen should be able to
+# find.
+#------------------------------------------------------------------------------
+function( set_doxygen_image_path )
+  # 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}" PARENT_SCOPE)
+  unset( temp )
+endfunction()
+
+#------------------------------------------------------------------------------
+# Set the number of cpu threads to use when generating the documentation.
+#------------------------------------------------------------------------------
+function( set_doxygen_dot_num_threads )
+  # Doxygen only allows 32 threads max
+  if( ${MPIEXEC_MAX_NUMPROCS} GREATER 32 )
+    set( DOXYGEN_DOT_NUM_THREADS 32 PARENT_SCOPE)
+  else()
+    set( DOXYGEN_DOT_NUM_THREADS ${MPIEXEC_MAX_NUMPROCS} PARENT_SCOPE)
+  endif()
+endfunction()
+
+#------------------------------------------------------------------------------
+# Generate and install HTML support files
+#
+# Requires the following variables to be set:
+# - PROJECT_SOURCE_DIR - Always provided by CMake (but should point to the to
+#     top level source directory.
+# - DOXYGEN_OUTPUT_DIR - Directory where html code will be written by
+#     doxygen. Actual location of HTML files will be
+#     ${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}.
+# - DOXYGEN_HTML_OUTPUT - The project name in all lowercase.
+#------------------------------------------------------------------------------
+macro( doxygen_provide_support_files )
+  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 )
+
+  if( EXISTS "${draco_config_dir}/doxygen.css" )
+    # use Draco's version of the style sheet
+    set( doxygen_ccs_file "${draco_config_dir}/doxygen.css" )
+  elseif( EXISTS "${PROJECT_SOURCE_DIR}/autodoc/html/doxygen.css" )
+    # use Draco's version of the style sheet
+    set( doxygen_ccs_file "${PROJECT_SOURCE_DIR}/autodoc/html/doxygen.css" )
+  else()
+    message( FATAL_ERROR "I can't find a style sheet to install for autodoc.
+Expected to find doxygen.css at either
+- ${draco_config_dir}/, or
+- {PROJECT_SOURCE_DIR}/autodoc/html/" )
+  endif()
+  add_custom_command(
+    OUTPUT  "${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/doxygen.css"
+    COMMAND "${CMAKE_COMMAND}"
+            -DINFILE="${doxygen_ccs_file}"
+            -DOUTFILE="${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}/doxygen.css"
+            -P "${draco_config_dir}/configureFileOnMake.cmake"
+    DEPENDS "${doxygen_css_file}" )
+endmacro()
+
+#------------------------------------------------------------------------------
+# Create a string to locate Draco.tag
+#------------------------------------------------------------------------------
+function( set_doxygen_tagfiles )
+  # Create links to Draco autodoc installation.
+  unset( DRACO_TAG_FILE CACHE )
+  find_file( DRACO_TAG_FILE Draco.tag
+    HINTS ${DOXYGEN_OUTPUT_DIR} )
+  get_filename_component( DRACO_AUTODOC_DIR ${DRACO_TAG_FILE} PATH )
+  file( RELATIVE_PATH DRACO_AUTODOC_HTML_DIR
+    ${DOXYGEN_OUTPUT_DIR}/${DOXYGEN_HTML_OUTPUT}
+    ${DRACO_AUTODOC_DIR}/draco )
+  set( TAGFILES "${DRACO_TAG_FILE}=${DRACO_AUTODOC_HTML_DIR}" PARENT_SCOPE)
+endfunction()
+
+#------------------------------------------------------------------------------#
+# End config/autodoc_macros.cmake
+#------------------------------------------------------------------------------#

src/diagnostics/draco_info_main.cc

@@ -10,6 +10,7 @@
 
 #include "draco_info.hh"
 #include "ds++/Assert.hh"
+#include "ds++/Release.hh"
 #include "ds++/XGetopt.hh"
 #include <iostream>
 
@@ -19,22 +20,36 @@ int main(int argc, char *argv[]) {
   try {
     bool version(false);
     bool brief(false);
+    bool author(false);
+    bool use_doxygen_formatting(false);
     rtt_diagnostics::DracoInfo di;
 
     // Preparing to parse command line arguments.
     rtt_dsxx::XGetopt::csmap long_options;
+    long_options['a'] = "author";
     long_options['b'] = "brief";
+    long_options['d'] = "use_doxygen_formatting";
     long_options['h'] = "help";
     long_options['v'] = "version";
     std::map<char, std::string> help_strings;
+    help_strings['a'] = "print the author list.";
     help_strings['b'] = "print a brief message.";
+    help_strings['d'] = "Add extra formatting (doxygen) to output strings.";
     help_strings['v'] = "print version information and exit.";
     help_strings['h'] = "print this message.";
     rtt_dsxx::XGetopt program_options(argc, argv, long_options, help_strings);
 
     int c(0);
     while ((c = program_options()) != -1) {
       switch (c) {
+      case 'a': // --author
+        author = true;
+        break;
+
+      case 'd': // --use_doxygen_formatting
+        use_doxygen_formatting = true;
+        break;
+
       case 'v': // --version
         version = true;
         break;
@@ -57,6 +72,8 @@ int main(int argc, char *argv[]) {
       cout << di.versionReport();
     else if (brief)
       cout << di.briefReport();
+    else if (author)
+      cout << rtt_dsxx::author_list(use_doxygen_formatting);
     else
       cout << di.fullReport();
   } catch (rtt_dsxx::assertion &err) {

src/ds++/Release.hh

@@ -26,7 +26,7 @@ typedef std::pair<int, std::string> fomdev;
 //! Query package for the release number.
 const std::string release();
 //! Return a list of Draco authors
-const std::string author_list();
+const std::string author_list(bool const use_doxygen_formatting = false);
 //! Return a list of Draco authors
 const std::string copyright();