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@/osal/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@/osal/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