Merge pull request #2058 from skliper/fix2055-doxygen_frontpage

Fix #2055, Refactor doxygen mainpage into frontpage

cmake/cfe-common.doxyfile.in

@@ -1,19 +1,9 @@
 #---------------------------------------------------------------------------
-# 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
+
+PREDEFINED            += @CFEDOC_PREDEFINED@
+
 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\" " \
@@ -34,33 +24,11 @@ ALIASES               += "cfeescfg=\xrefitem cfeescfg \"Purpose\" \"cFE Executiv
                          "cfecmdmnemonic=\xrefitem cfecmdmnems \"Command Mnemonic(s)\" \"cFE Command Mnemonic Cross Reference\" " \
                          "cfetlmmnemonic=\xrefitem cfetlmmnems \"Telemetry Mnemonic(s)\" \"cFE Telemetry Mnemonic Cross Reference\" "
 
-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,55 +39,13 @@ 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*/*"
+# Public headers
+INPUT                 += @MISSION_USERGUIDE_HEADERFILES@
 
-# 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

cmake/cfe-usersguide.doxyfile.in

@@ -2,26 +2,20 @@
 # 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
+# Allow overrides
+@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
 
-# Common definitions, some of which are extended or overridden here.
+# Common configuration and default settings
 @INCLUDE               = @MISSION_BINARY_DIR@/docs/cfe-common.doxyfile
+@INCLUDE               = @MISSION_SOURCE_DIR@/cfe/docs/src/default-settings.doxyfile
+
+# Document specific settings
 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
 # interested in the documentation of those items.
 STRIP_FROM_PATH       += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
-
-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,35 @@
 #---------------------------------------------------------------------------
-# 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.
+# Allow overrides
+@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
+
+# Common configuration and default settings
 @INCLUDE               = @MISSION_BINARY_DIR@/docs/cfe-common.doxyfile
+@INCLUDE               = @MISSION_SOURCE_DIR@/cfe/docs/src/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 stand alone repo documentation
+EXCLUDE_PATTERNS       += "*/CODE_OF_CONDUCT.md"
+EXCLUDE_PATTERNS       += "*/CONTRIBUTING.md"
+EXCLUDE_PATTERNS       += "*/README.md"
+EXCLUDE_PATTERNS       += "*/SECURITY.md"

cmake/mission_build.cmake

@@ -280,10 +280,6 @@ function(prepare)
   string(CONCAT DETAILDESIGN_DOXYFILE_USER_CONTENT ${DETAILDESIGN_DOXYFILE_USER_CONTENT})
   string(CONCAT TGTSYSTEM_DOXYFILE_USER_CONTENT ${TGTSYSTEM_DOXYFILE_USER_CONTENT})
 
-  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/docs/cfe-common.doxyfile"
-    @ONLY)
-
   # Generate an "empty" osconfig.h file for doxygen purposes
   # this does not have the actual user-defined values, but will
   # have the documentation associated with each macro definition.
@@ -307,6 +303,10 @@ function(prepare)
 
   string(REPLACE ";" " \\\n" MISSION_USERGUIDE_HEADERFILES "${MISSION_USERGUIDE_HEADERFILES}")
 
+  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/docs/cfe-common.doxyfile"
+    @ONLY)
+
   file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/docs/detaildesign")
   configure_file("${CFE_SOURCE_DIR}/cmake/mission-detaildesign.doxyfile.in"
     "${CMAKE_BINARY_DIR}/docs/detaildesign/Doxyfile"

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,55 @@
+#---------------------------------------------------------------------------
+# Default Doxygen settings
+#---------------------------------------------------------------------------
+
+# Common aliases
+ALIASES               +=  nonnull="(must not be null)"
+ALIASES               +=  nonzero="(must not be zero)"
+ALIASES               +=  covtest="(return value only verified in coverage test)"
+
+# Source options
+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