From d89c7ce785fc28b4fc2e79963e44493901daa58a Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Tue, 8 Jun 2021 10:55:43 -0400 Subject: [PATCH 1/2] 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 | 20 ++---- cmake/cfe-common.doxyfile.in | 7 ++- cmake/cfe-usersguide.doxyfile.in | 3 +- cmake/mission-detaildesign.doxyfile.in | 23 ++----- cmake/mission_build.cmake | 87 +++++++++++++++++--------- 5 files changed, 73 insertions(+), 67 deletions(-) diff --git a/cmake/arch_build.cmake b/cmake/arch_build.cmake index 7c2e6466e..383a19bcd 100644 --- a/cmake/arch_build.cmake +++ b/cmake/arch_build.cmake @@ -611,21 +611,11 @@ 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" - "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") + # 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 += ${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..57a0b18b7 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,12 @@ 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*/*" + #--------------------------------------------------------------------------- # configuration options related to source browsing #--------------------------------------------------------------------------- diff --git a/cmake/cfe-usersguide.doxyfile.in b/cmake/cfe-usersguide.doxyfile.in index a884a342e..0198d4a81 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 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..0f3a48013 100644 --- a/cmake/mission_build.cmake +++ b/cmake/mission_build.cmake @@ -241,36 +241,58 @@ 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") + # Add any detail design information from each app/module 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() + + # There is some historical inconsistency in whether submodules have documentation + # in a "docs" or "doc" subdirectory. Most GSFC CFS apps now use "docs" but OSAL + # had traditionally been "doc". For best compatibility, either will be accepted/used. + # if no documentation dir is found, then just look for doxyfiles in the app dir + if (IS_DIRECTORY "${${APP}_MISSION_DIR}/docs") + set(APP_DOC_DIR "${${APP}_MISSION_DIR}/docs") + elseif(IS_DIRECTORY "${${APP}_MISSION_DIR}/doc") + set(APP_DOC_DIR "${${APP}_MISSION_DIR}/doc") + else() + set(APP_DOC_DIR "${${APP}_MISSION_DIR}") + endif() + + # Now add the app-specific documentation to the detail design input set. + # This depends on whether the app has provided any guidance on this. + # The "doxyfile.in" should provide specific directives for what to include. If + # not specified, then the entire app source tree will be used as a catch-all. + if (EXISTS "${APP_DOC_DIR}/${APP}-detaildesign.doxyfile.in") + + # a "doxyfile.in" is a template that should be passed through configure_file() + # (which will expand any variable refs) then the result of this is included in the doxyfile + configure_file("${APP_DOC_DIR}/${APP}-detaildesign.doxyfile.in" + "${CMAKE_BINARY_DIR}/doc/${APP}-detaildesign.doxyfile") + + list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/${APP}-detaildesign.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 +317,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 From c67f217e82af2068d46c197ea97aba93e20b9911 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Tue, 8 Jun 2021 11:40:14 -0400 Subject: [PATCH 2/2] Fix #1589, Separate warning file for doc builds Use a unique file name for the doxygen warnings, instead of "warnings.log", so the mutiple documentation targets will not overwrite the other log file. Use a prefixed name so that if the log file is uploaded to the build artifacts, it will be identifiable. Detail Design warnings in: detaildesign-warnings.log Users Guide warnings in: cfe-usersguide-warnings.log --- cmake/cfe-common.doxyfile.in | 1 - cmake/cfe-usersguide.doxyfile.in | 1 + cmake/mission-detaildesign.doxyfile.in | 1 + 3 files changed, 2 insertions(+), 1 deletion(-) diff --git a/cmake/cfe-common.doxyfile.in b/cmake/cfe-common.doxyfile.in index 57a0b18b7..8e504d4af 100644 --- a/cmake/cfe-common.doxyfile.in +++ b/cmake/cfe-common.doxyfile.in @@ -54,7 +54,6 @@ GENERATE_DEPRECATEDLIST= YES # configuration options related to warning and progress messages #--------------------------------------------------------------------------- WARN_NO_PARAMDOC = YES -WARN_LOGFILE = @CMAKE_BINARY_DIR@/doc/warnings.log #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- diff --git a/cmake/cfe-usersguide.doxyfile.in b/cmake/cfe-usersguide.doxyfile.in index 0198d4a81..a610c1cd5 100644 --- a/cmake/cfe-usersguide.doxyfile.in +++ b/cmake/cfe-usersguide.doxyfile.in @@ -9,6 +9,7 @@ INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox @INCLUDE = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile PROJECT_NAME = "Core Flight Executive Users Guide" OUTPUT_DIRECTORY = @CMAKE_BINARY_DIR@/doc/users_guide +WARN_LOGFILE = @CMAKE_BINARY_DIR@/doc/cfe-usersguide-warnings.log GENERATE_LATEX = YES # For purposes of the user guide, reference the "stock" mission configuration diff --git a/cmake/mission-detaildesign.doxyfile.in b/cmake/mission-detaildesign.doxyfile.in index 180f87522..fe7c1f9d8 100644 --- a/cmake/mission-detaildesign.doxyfile.in +++ b/cmake/mission-detaildesign.doxyfile.in @@ -7,6 +7,7 @@ PROJECT_NAME = "@MISSION_NAME@" PROJECT_BRIEF = "Core Flight System project built using \"@MISSIONCONFIG@\" configuration" OUTPUT_DIRECTORY = @CMAKE_BINARY_DIR@/doc/detaildesign +WARN_LOGFILE = @CMAKE_BINARY_DIR@/doc/detaildesign-warnings.log INPUT += @MISSION_DEFS@ STRIP_FROM_PATH += @MISSION_DEFS@