Fix nasa#2055, Refactor doxygen mainpage into frontpage

cmake/cfe-common.doxyfile.in

@@ -1,19 +1,7 @@
 #---------------------------------------------------------------------------
-# Project related configuration options, shared for all cFE doxygen outputs
+# CFE common setup for including in stand alone or mission documentation
 #---------------------------------------------------------------------------
-@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
-ABBREVIATE_BRIEF       = "The $name class " \
-                         "The $name widget " \
-                         "The $name file " \
-                         is \
-                         provides \
-                         specifies \
-                         contains \
-                         represents \
-                         a \
-                         an \
-                         the
-TAB_SIZE               = 8
+
 ALIASES               += "cfeescfg=\xrefitem cfeescfg \"Purpose\" \"cFE Executive Services Configuration Parameters\" " \
                          "cfeevscfg=\xrefitem cfeevscfg \"Purpose\" \"cFE Event Services Configuration Parameters\" " \
                          "cfetblcfg=\xrefitem cfetblcfg \"Purpose\" \"cFE Table Services Configuration Parameters\" " \
@@ -38,29 +26,11 @@ ALIASES               +=  nonnull="(must not be null)"
 ALIASES               +=  nonzero="(must not be zero)"
 ALIASES               +=  covtest="(return value only verified in coverage test)"
 
-OPTIMIZE_OUTPUT_FOR_C  = YES
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = YES
-EXTRACT_STATIC         = YES
-CASE_SENSE_NAMES       = NO
-GENERATE_TODOLIST      = NO
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-WARN_NO_PARAMDOC       = YES
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-STRIP_FROM_PATH        = @MISSION_SOURCE_DIR@
-
 # Always include a standard set of CFE documentation in the input set
-# This is applicable to both users guide and detail design outputs
 IMAGE_PATH            += @MISSION_SOURCE_DIR@/cfe/docs/src
+
+# Front documentation material
+INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_frontpage.dox
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_glossary.dox
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfs_versions.dox
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_api.dox
@@ -71,62 +41,17 @@ INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_tbl.dox
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_time.dox
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_xref.dox
 
-FILE_PATTERNS          = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md
-RECURSIVE              = YES
-EXAMPLE_PATTERNS       = *
-
-# Exclude coverage tests, stubs and associated framework from the documentation
-EXCLUDE_PATTERNS       += "*/ut-stubs/*"
-EXCLUDE_PATTERNS       += "*/ut-coverage/*"
-EXCLUDE_PATTERNS       += "*/unit-test*/*"
-
-# Exclude contributing guides and readme's since they stand alone as repo documentation
-EXCLUDE_PATTERNS       += "*/CONTRIBUTING.md"
-EXCLUDE_PATTERNS       += "*/README.md"
+# Strip mission from path
+STRIP_FROM_PATH        = @MISSION_SOURCE_DIR@
 
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = YES
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION    = YES
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_CMD_NAME         = latex
-COMPACT_LATEX          = YES
-PAPER_TYPE             = letter
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-COMPACT_RTF            = YES
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = NO
-HAVE_DOT               = YES
-CLASS_GRAPH            = NO
-COLLABORATION_GRAPH    = NO
-INCLUDE_GRAPH          = NO
-INCLUDED_BY_GRAPH      = NO
-CALL_GRAPH             = YES
-GRAPHICAL_HIERARCHY    = NO
-MAX_DOT_GRAPH_DEPTH    = 1000
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine
-#---------------------------------------------------------------------------
-SEARCHENGINE           = NO
-#---------------------------------------------------------------------------
-# CFE mnemonic mappings
-#---------------------------------------------------------------------------
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_es_cmd_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_es_tlm_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_tbl_cmd_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_tbl_tlm_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_time_cmd_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_time_tlm_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_evs_cmd_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_evs_tlm_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_sb_cmd_mnem_map
-@INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_sb_tlm_mnem_map
+# CFE mnemonic mappings, must be in @INCLUDE_PATH
+@INCLUDE = cfe_es_cmd_mnem_map
+@INCLUDE = cfe_es_tlm_mnem_map
+@INCLUDE = cfe_tbl_cmd_mnem_map
+@INCLUDE = cfe_tbl_tlm_mnem_map
+@INCLUDE = cfe_time_cmd_mnem_map
+@INCLUDE = cfe_time_tlm_mnem_map
+@INCLUDE = cfe_evs_cmd_mnem_map
+@INCLUDE = cfe_evs_tlm_mnem_map
+@INCLUDE = cfe_sb_cmd_mnem_map
+@INCLUDE = cfe_sb_tlm_mnem_map

cmake/cfe-usersguide.doxyfile.in

@@ -2,15 +2,21 @@
 # Doxygen Configuration options to generate the "cFE Users Guide"
 #---------------------------------------------------------------------------
 
-# Start with the main page so document ordering is established
-INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox
+# Mission, build, static search for @INCLUDE to allow overrides
+@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
+@INCLUDE_PATH         += @MISSION_BINARY_DIR@/docs
+@INCLUDE_PATH         += @MISSION_SOURCE_DIR@/cfe/docs/src
+@INCLUDE_PATH         += @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps
+
+# Common configuration and default settings can be overridden
+@INCLUDE               = cfe-common.doxyfile
+@INCLUDE               = default-settings.doxyfile
 
 # Common definitions, some of which are extended or overridden here.
 @INCLUDE               = @MISSION_BINARY_DIR@/docs/cfe-common.doxyfile
 PROJECT_NAME           = "Core Flight Executive Users Guide"
 OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/users_guide
 WARN_LOGFILE           = @CMAKE_BINARY_DIR@/docs/cfe-usersguide-warnings.log
-GENERATE_LATEX         = YES
 
 # For purposes of the user guide, reference the "stock" mission configuration
 # Although missions may override these files, for the users guide we are mainly
@@ -22,6 +28,3 @@ PREDEFINED            += @USERGUIDE_PREDEFINED@
 
 # Bring in the cFE header files for the documentation of the various API calls
 INPUT                 += @MISSION_USERGUIDE_HEADERFILES@
-
-# Resolve references
-INPUT                 += @MISSION_SOURCE_DIR@/psp/fsw/inc

cmake/mission-detaildesign.doxyfile.in

@@ -1,19 +1,37 @@
 #---------------------------------------------------------------------------
-# Doxygen options to generate the complete mission documentation
+# Sample doxygen setup for generating mission documentation
 #---------------------------------------------------------------------------
 
-# Start with the common definitions, some of which are extended or overridden here.
+# Mission, build, static search for @INCLUDE to allow overrides
+@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
+@INCLUDE_PATH         += @MISSION_BINARY_DIR@/docs
+@INCLUDE_PATH         += @MISSION_SOURCE_DIR@/cfe/docs/src
+@INCLUDE_PATH         += @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps
+
+# Common configuration and default settings can be overridden
+SEARCH_INCLUDES        = YES
 @INCLUDE               = @MISSION_BINARY_DIR@/docs/cfe-common.doxyfile
+@INCLUDE               = default-settings.doxyfile
+
+# Example detailed design setup
 PROJECT_NAME           = "@MISSION_NAME@"
 PROJECT_BRIEF          = "Core Flight System project built using \"@MISSIONCONFIG@\" configuration"
 OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/detaildesign
 WARN_LOGFILE           = @CMAKE_BINARY_DIR@/docs/detaildesign-warnings.log
 
+# Include mission defs directory
 INPUT                 += @MISSION_DEFS@
 STRIP_FROM_PATH       += @MISSION_DEFS@
 
-#---------------------------------------------------------------------------
 # The user content doxyfile contains paths to the mission-specific applications
-#---------------------------------------------------------------------------
 @DETAILDESIGN_DOXYFILE_USER_CONTENT@
 @TGTSYSTEM_DOXYFILE_USER_CONTENT@
+
+# Exclude coverage tests, stubs and associated framework from the documentation
+EXCLUDE_PATTERNS       += "*/ut-stubs/*"
+EXCLUDE_PATTERNS       += "*/ut-coverage/*"
+EXCLUDE_PATTERNS       += "*/unit-test*/*"
+
+# Exclude contributing guides and readme's since they stand alone as repo documentation
+EXCLUDE_PATTERNS       += "*/CONTRIBUTING.md"
+EXCLUDE_PATTERNS       += "*/README.md"

docs/src/main.dox → docs/src/cfe_frontpage.dox

@@ -1,5 +1,5 @@
 /**
-  \mainpage Core Flight Executive Documentation
+  \page cfefrontpage Core Flight Executive Documentation
 
   <UL>
     <LI> General Information and Concepts

docs/src/default-settings.doxyfile

@@ -0,0 +1,48 @@
+#---------------------------------------------------------------------------
+# Default Doxygen settings, can be included or replaced at mission level
+#---------------------------------------------------------------------------
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+# Build related
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+CASE_SENSE_NAMES       = NO
+GENERATE_TODOLIST      = NO
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+
+# Warnings
+WARN_NO_PARAMDOC       = YES
+
+# Matching
+FILE_PATTERNS          = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md
+RECURSIVE              = YES
+
+# Source browsing
+SOURCE_BROWSER         = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+
+# LaTeX output
+GENERATE_LATEX         = YES
+LATEX_CMD_NAME         = latex
+COMPACT_LATEX          = YES
+PAPER_TYPE             = letter
+
+# RTF output
+COMPACT_RTF            = YES
+
+# Dot tool
+CLASS_DIAGRAMS         = NO
+HAVE_DOT               = YES
+CLASS_GRAPH            = NO
+COLLABORATION_GRAPH    = NO
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
+CALL_GRAPH             = YES
+GRAPHICAL_HIERARCHY    = NO
+MAX_DOT_GRAPH_DEPTH    = 1000
+
+# Search engine
+SEARCHENGINE           = NO