From 1c6aa9df30faa067e4d278ba6dcf0dbac83524c4 Mon Sep 17 00:00:00 2001 From: Jacob Hageman Date: Thu, 24 Feb 2022 13:40:01 -0700 Subject: [PATCH] Fix #1227, Refactor doxygen and remove mainpage --- docs/osal-detaildesign.doxyfile.in | 7 ++ docs/src/CMakeLists.txt | 7 +- docs/src/default-settings.doxyfile | 55 +++++++++++++ docs/src/osal-apiguide.doxyfile.in | 5 -- docs/src/osal-common.doxyfile.in | 81 +++---------------- docs/src/{osalmain.dox => osal_frontpage.dox} | 2 +- 6 files changed, 78 insertions(+), 79 deletions(-) create mode 100644 docs/src/default-settings.doxyfile rename docs/src/{osalmain.dox => osal_frontpage.dox} (98%) diff --git a/docs/osal-detaildesign.doxyfile.in b/docs/osal-detaildesign.doxyfile.in index ee0602016..f5efaf070 100644 --- 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 index 589da9a30..a8e5191d1 100644 --- 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,6 +63,7 @@ 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( @@ -70,6 +71,7 @@ configure_file( ${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 new file mode 100644 index 000000000..9b7f9ef9e --- /dev/null +++ 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 index 86c0de81b..b6bde31e9 100644 --- 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 index 39bbba061..32ff2099f 100644 --- 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 b/docs/src/osal_frontpage.dox similarity index 98% rename from docs/src/osalmain.dox rename to docs/src/osal_frontpage.dox index fee3a1c72..b05a8eac3 100644 --- a/docs/src/osalmain.dox +++ b/docs/src/osal_frontpage.dox @@ -1,5 +1,5 @@ /** - \mainpage Osal API Documentation + \page osalfrontpage Osal API Documentation