Merge pull request nasa#1228 from skliper/fix1227-doxygen_mainpage

Fix nasa#1227, Refactor doxygen and remove mainpage
chillfig · Mar 7, 2022 · a173f30 · a173f30
2 parents 92fbf08 + 1c6aa9d
commit a173f30
Show file tree

Hide file tree

Showing 6 changed files with 78 additions and 79 deletions.
diff --git a/docs/osal-detaildesign.doxyfile.in b/docs/osal-detaildesign.doxyfile.in
@@ -1,3 +1,10 @@
+#---------------------------------------------------------------------------
+# Doxygen Configuration options for mission detailed documentation
+#---------------------------------------------------------------------------
+
+# Common files
+@INCLUDE  = @MISSION_BINARY_DIR@/docs/osalguide/osal-common.doxyfile
+
 # All of the OSAL FSW code relevant for a detail design document is under
 # src/os and src/bsp, everything else is test and examples/support
 # Note this will include ALL OS/BSP layers, it does not currently filter

diff --git a/docs/src/CMakeLists.txt b/docs/src/CMakeLists.txt
@@ -34,7 +34,7 @@ project(OSAL_DOCS NONE)
 # List of dox files to include -
 # note that order is relevant here, doxygen processes in the order listed.
 set(OSAL_DOCFILE_LIST
-    ${CMAKE_CURRENT_SOURCE_DIR}/osalmain.dox
+    ${CMAKE_CURRENT_SOURCE_DIR}/osal_frontpage.dox
     ${CMAKE_CURRENT_SOURCE_DIR}/osal_fs.dox
     ${CMAKE_CURRENT_SOURCE_DIR}/osal_timer.dox
 )
@@ -63,13 +63,15 @@ endforeach()
 file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide-warnings.log OSAL_NATIVE_LOGFILE)
 file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile OSAL_NATIVE_COMMON_CFGFILE)
 file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile OSAL_NATIVE_APIGUIDE_CFGFILE)
+file(TO_NATIVE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/default-settings.doxyfile OSAL_NATIVE_DEFAULT_SETTINGS)
 
 # generate the configuration files
 configure_file(
         ${CMAKE_CURRENT_SOURCE_DIR}/osal-common.doxyfile.in
         ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile
         @ONLY
 )
+
 configure_file(
         ${CMAKE_CURRENT_SOURCE_DIR}/osal-apiguide.doxyfile.in
         ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile
@@ -78,7 +80,8 @@ configure_file(
 
 add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html"
     COMMAND doxygen ${OSAL_NATIVE_APIGUIDE_CFGFILE}
-    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile ${OSAL_DOCFILE_LIST} ${OSAL_DOC_DEPENDENCY_LIST}
+    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile
+            ${OSAL_DOCFILE_LIST} ${OSAL_DOC_DEPENDENCY_LIST}
     WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
 )
 

diff --git a/docs/src/default-settings.doxyfile b/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
diff --git a/docs/src/osal-apiguide.doxyfile.in b/docs/src/osal-apiguide.doxyfile.in
@@ -2,15 +2,10 @@
 # Doxygen Configuration options to generate the "OSAL API Guide"
 #---------------------------------------------------------------------------
 
-# Complete list of input files
-INPUT += @OSAL_NATIVE_APIGUIDE_SOURCEFILES@
-
-
 # Common definitions, some of which are extended or overridden here.
 @INCLUDE               = @OSAL_NATIVE_COMMON_CFGFILE@
 PROJECT_NAME           = "OSAL User's Guide"
 OUTPUT_DIRECTORY       = apiguide
-GENERATE_LATEX         = YES
 
 # output the warnings to a separate file
 WARN_LOGFILE           = @OSAL_NATIVE_LOGFILE@
diff --git a/docs/src/osal-common.doxyfile.in b/docs/src/osal-common.doxyfile.in
@@ -1,76 +1,15 @@
 #---------------------------------------------------------------------------
-# Project related configuration options, shared for all cFE doxygen outputs
+# OSAL common setup for including in stand alone or mission documentation
 #---------------------------------------------------------------------------
-@INCLUDE_PATH          = @OSAL_NATIVE_INCLUDE_DIRS@
-OUTPUT_DIRECTORY       = .
-ABBREVIATE_BRIEF       = "The $name class " \
-                         "The $name widget " \
-                         "The $name file " \
-                         is \
-                         provides \
-                         specifies \
-                         contains \
-                         represents \
-                         a \
-                         an \
-                         the
-TAB_SIZE               = 4
-OPTIMIZE_OUTPUT_FOR_C  = YES
-ALIASES               +=  nonnull="(must not be null)"
-ALIASES               +=  nonzero="(must not be zero)"
-ALIASES               +=  covtest="(return value only verified in coverage test)"
 
+# Allow overrides
+@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
+
+# Default settings from cFE
+@INCLUDE               = @OSAL_NATIVE_DEFAULT_SETTINGS@
+
+# Include any passed in predefines
 PREDEFINED            += @OSALDOC_PREDEFINED@
 
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = YES
-EXTRACT_STATIC         = YES
-CASE_SENSE_NAMES       = NO
-GENERATE_TODOLIST      = NO
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-WARN_NO_PARAMDOC       = YES
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-STRIP_FROM_PATH        = @OSAL_SOURCE_NATIVE_DIR@
-FILE_PATTERNS          = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md
-RECURSIVE              = YES
-EXAMPLE_PATTERNS       = *
-#---------------------------------------------------------------------------
-# 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
+# Minimum set of source files (includes *.dox, followed by public headers)
+INPUT                 += @OSAL_NATIVE_APIGUIDE_SOURCEFILES@
diff --git a/docs/src/osalmain.dox → docs/src/osal_frontpage.dox b/docs/src/osalmain.dox → docs/src/osal_frontpage.dox
@@ -1,5 +1,5 @@
 /**
-  \mainpage Osal API Documentation
+  \page osalfrontpage Osal API Documentation
 
   <UL>
     <LI> General Information and Concepts