From c742819da9eeb85bd61905db35b86670c2dfc1d3 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Tue, 8 Jun 2021 10:55:43 -0400 Subject: [PATCH] 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. --- cmake/arch_build.cmake | 19 ++------ cmake/cfe-common.doxyfile.in | 16 ++++++- cmake/cfe-usersguide.doxyfile.in | 6 ++- cmake/mission-detaildesign.doxyfile.in | 23 ++------- cmake/mission_build.cmake | 65 ++++++++++++++------------ 5 files changed, 63 insertions(+), 66 deletions(-) diff --git a/cmake/arch_build.cmake b/cmake/arch_build.cmake index 7c2e6466e..f80f21b57 100644 --- 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 index d1c53f9ea..9a8720a4b 100644 --- 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 index a884a342e..3b2166d36 100644 --- 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,7 +17,6 @@ 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 @@ -25,3 +24,6 @@ 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 index 0e9aa60d7..180f87522 100644 --- 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 index f024f864b..87449e4b3 100644 --- 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