Fix #1378, simplify doxygen configs

Put the "detaildesign" and "users_guide" into separate working directories, and do a general cleanup/simplification of the generated doxyfiles. Detail design just includes all components, and use "exclude" where special treatment was needed, and to avoid UT code. Paths for each "arch" (target-specific) are written to separate files and included directly in the generated doxyfile, reducing the number of generated files/layers.
nasa · Jun 8, 2021 · c742819 · c742819
1 parent a16c78e
commit c742819
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 66 deletions.
diff --git a/cmake/arch_build.cmake b/cmake/arch_build.cmake
@@ -611,21 +611,12 @@ function(process_arch SYSVAR)
   # This can help with debugging if things go wrong.
   message(STATUS "PSP Selection: ${CFE_SYSTEM_PSPNAME}")
 
-  # Append the PSP and OSAL selections to the Doxyfile so it will be included
-  # in the generated documentation automatically.
-  # Also extract the "-D" options within CFLAGS and inform Doxygen about these
-  string(REGEX MATCHALL "-D[A-Za-z0-9_=]+" DOXYGEN_DEFINED_MACROS "${CMAKE_C_FLAGS}")
-  string(REGEX REPLACE "-D" " " DOXYGEN_DEFINED_MACROS "${DOXYGEN_DEFINED_MACROS}")
-  file(APPEND "${MISSION_BINARY_DIR}/doc/mission-content.doxyfile"
-    "PREDEFINED += ${DOXYGEN_DEFINED_MACROS}\n"
-    "INPUT += ${MISSION_SOURCE_DIR}/osal/src/os/${OSAL_SYSTEM_OSTYPE}\n"
+  # Create a documentation content file, with any system-specific doxygen info
+  # this is done here in arch_build where the CFE_SYSTEM_PSPNAME is known
+  file(WRITE "${MISSION_BINARY_DIR}/doc/tgtsystem-content-${SYSVAR}.doxyfile"
     "INPUT += ${MISSION_SOURCE_DIR}/psp/fsw/${CFE_SYSTEM_PSPNAME}\n"
-    "INPUT += ${CMAKE_BINARY_DIR}/inc")
-
-  # Append to usersguide.doxyfile
-  file(APPEND "${MISSION_BINARY_DIR}/doc/cfe-usersguide.doxyfile"
-    "INPUT += ${MISSION_SOURCE_DIR}/psp/fsw/${CFE_SYSTEM_PSPNAME}/src\n"
-    "INPUT += ${CMAKE_BINARY_DIR}/inc")
+    "INPUT += ${CMAKE_BINARY_DIR}/inc\n"
+  )
 
   # The PSP and/or OSAL should have defined where to install the binaries.
   # If not, just install them in /cf as a default (this can be modified

diff --git a/cmake/cfe-common.doxyfile.in b/cmake/cfe-common.doxyfile.in
@@ -2,7 +2,6 @@
 # Project related configuration options, shared for all cFE doxygen outputs
 #---------------------------------------------------------------------------
 @INCLUDE_PATH          = @MISSION_SOURCE_DIR@
-OUTPUT_DIRECTORY       = .
 ABBREVIATE_BRIEF       = "The $name class " \
                          "The $name widget " \
                          "The $name file " \
@@ -77,6 +76,21 @@ 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 test stubs, examples, and test framework from the documentation
+EXCLUDE_PATTERNS       += "*/ut-stubs/*"
+EXCLUDE_PATTERNS       += "*/ut-coverage/*"
+EXCLUDE_PATTERNS       += "*/examples/*"
+EXCLUDE_PATTERNS       += "*/tests/*"
+EXCLUDE_PATTERNS       += "*/unit-test*/*"
+
+# Exclude UT assert itself (part of OSAL)
+EXCLUDE                += @MISSION_SOURCE_DIR@/osal/ut_assert
+
+# Also exclude the OSAL main documentation from the cFE doc build
+# (this may create a conflict by having more than one main page)
+EXCLUDE                += @MISSION_SOURCE_DIR@/osal/doc
+
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
 #---------------------------------------------------------------------------

diff --git a/cmake/cfe-usersguide.doxyfile.in b/cmake/cfe-usersguide.doxyfile.in
@@ -8,7 +8,7 @@ INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox
 # Common definitions, some of which are extended or overridden here.
 @INCLUDE               = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile
 PROJECT_NAME           = "Core Flight Executive Users Guide"
-OUTPUT_DIRECTORY       = users_guide
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/doc/users_guide
 GENERATE_LATEX         = YES
 
 # For purposes of the user guide, reference the "stock" mission configuration
@@ -17,11 +17,13 @@ GENERATE_LATEX         = YES
 STRIP_FROM_PATH       += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 
-#PREDEFINED
 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
+
+# List of target system-specific inputs
+@TGTSYSTEM_DOXYFILE_USER_CONTENT@
diff --git a/cmake/mission-detaildesign.doxyfile.in b/cmake/mission-detaildesign.doxyfile.in
@@ -6,28 +6,13 @@
 @INCLUDE               = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile
 PROJECT_NAME           = "@MISSION_NAME@"
 PROJECT_BRIEF          = "Core Flight System project built using \"@MISSIONCONFIG@\" configuration"
-OUTPUT_DIRECTORY       = detaildesign
-
-INPUT                 += @MISSION_DEFS@  \
-                         @MISSION_SOURCE_DIR@/osal/src/os/inc \
-                         @MISSION_SOURCE_DIR@/osal/src/os/shared \
-                         @MISSION_SOURCE_DIR@/psp/fsw/inc \
-                         @MISSION_SOURCE_DIR@/psp/fsw/shared \
-                         @MISSION_SOURCE_DIR@/cfe/modules/core_api/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/core_private/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/es/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/evs/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/fs/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/msg/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/resourceid/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/sb/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/sbr/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/tbl/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/time/fsw
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/doc/detaildesign
 
+INPUT                 += @MISSION_DEFS@
 STRIP_FROM_PATH       += @MISSION_DEFS@
 
 #---------------------------------------------------------------------------
 # The user content doxyfile contains paths to the mission-specific applications
 #---------------------------------------------------------------------------
-@INCLUDE               = @CMAKE_BINARY_DIR@/doc/mission-content.doxyfile
+@DETAILDESIGN_DOXYFILE_USER_CONTENT@
+@TGTSYSTEM_DOXYFILE_USER_CONTENT@
diff --git a/cmake/mission_build.cmake b/cmake/mission_build.cmake
@@ -241,36 +241,36 @@ function(prepare)
   # If the user has provided a "Doxyfile" in their top level documentation directory,
   # then assume they have also set PROJECT_NAME and PROJECT_BRIEF in that.
   # Otherwise, generate reasonable strings for these values.
-  set(MISSION_DOXYFILE_USER_CONTENT)
+  set(DETAILDESIGN_DOXYFILE_USER_CONTENT)
   if (EXISTS "${MISSION_SOURCE_DIR}/doc/Doxyfile")
-    list(APPEND MISSION_DOXYFILE_USER_CONTENT "@INCLUDE = ${MISSION_SOURCE_DIR}/doc/Doxyfile\n")
+    list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "@INCLUDE = ${MISSION_SOURCE_DIR}/doc/Doxyfile\n")
   endif (EXISTS "${MISSION_SOURCE_DIR}/doc/Doxyfile")
 
   foreach(APP ${MISSION_DEPS})
-    # OSAL is handled specially, as only part of it is used
-    if (NOT APP STREQUAL "osal")
-      if (EXISTS "${${APP}_MISSION_DIR}/docs/${APP}.doxyfile.in")
-        # If the module provides its own doxyfile, then include it directly
-        # This allows for app-specific fine-tuning of the sources, based on its own source tree
-        configure_file("${${APP}_MISSION_DIR}/docs/${APP}.doxyfile.in"
-            "${CMAKE_BINARY_DIR}/doc/${APP}.doxyfile")
-        list(APPEND MISSION_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/${APP}.doxyfile\n")
-      else()
-        # Otherwise just add this entire directory to the "INPUT" list
-        list(APPEND MISSION_DOXYFILE_USER_CONTENT "INPUT += ${${APP}_MISSION_DIR}\n")
-      endif()
+    if (EXISTS "${${APP}_MISSION_DIR}/docs/${APP}.doxyfile.in")
+      # If the module provides its own doxyfile, then include it directly
+      # This allows for app-specific fine-tuning of the sources, based on its own source tree
+      configure_file("${${APP}_MISSION_DIR}/docs/${APP}.doxyfile.in"
+          "${CMAKE_BINARY_DIR}/doc/${APP}.doxyfile")
+      list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/${APP}.doxyfile\n")
+    else()
+      # Otherwise just add this entire directory to the "INPUT" list
+      list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "INPUT += ${${APP}_MISSION_DIR}\n")
     endif()
   endforeach()
 
-  # In all cases it is assumed to include the CFE documentation as well (could be configurable?)
-  file(WRITE "${CMAKE_BINARY_DIR}/doc/mission-content.doxyfile"
-      ${MISSION_DOXYFILE_USER_CONTENT})
+  set(TGTSYSTEM_DOXYFILE_USER_CONTENT)
+  foreach(SYSVAR ${TGTSYS_LIST})
+    list(APPEND TGTSYSTEM_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/tgtsystem-content-${SYSVAR}.doxyfile\n")
+  endforeach()
 
-  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/doc/cfe-common.doxyfile")
+  # Create single/unified strings from the lists
+  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/mission-detaildesign.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/doc/mission-detaildesign.doxyfile")
+  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/cfe-common.doxyfile"
+    @ONLY)
 
   # Generate an "empty" osconfig.h file for doxygen purposes
   # this does not have the actual user-defined values, but will
@@ -295,16 +295,21 @@ function(prepare)
 
   string(REPLACE ";" " \\\n" MISSION_USERGUIDE_HEADERFILES "${MISSION_USERGUIDE_HEADERFILES}")
 
-  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-usersguide.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/doc/cfe-usersguide.doxyfile")
-
-  add_custom_target(mission-doc
-    doxygen mission-detaildesign.doxyfile
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc")
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/doc/detaildesign")
+  configure_file("${CFE_SOURCE_DIR}/cmake/mission-detaildesign.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/detaildesign/Doxyfile"
+    @ONLY)
+  add_custom_target(mission-doc doxygen
+    COMMAND echo "Detail Design: file://${CMAKE_BINARY_DIR}/doc/detaildesign/html/index.html"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc/detaildesign")
 
-  add_custom_target(cfe-usersguide
-    doxygen cfe-usersguide.doxyfile
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc")
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/doc/users_guide")
+  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-usersguide.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/users_guide/Doxyfile"
+    @ONLY)
+  add_custom_target(cfe-usersguide doxygen
+    COMMAND echo "Users Guide: file://${CMAKE_BINARY_DIR}/doc/users_guide/html/index.html"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc/users_guide")
 
   # OSAL API GUIDE include PUBLIC API
   set(OSAL_API_INCLUDE_DIRECTORIES