Merge pull request #2085 from skliper/fix2083-consistent_doxygen

Fix #2083, Fix #2086, Consistent doxygen flow/naming for generation and use reusable documentation generation workflow

.github/workflows/build-documentation.yml

@@ -1,17 +1,13 @@
-name: "Build cFE Documentation"
+name: cFS Documentation and Guides
 
 on:
   push:
   pull_request:
 
-env:
-  SIMULATION: native
-  BUILDTYPE: debug
-
 jobs:
-
-  #Check for duplicate actions. Skips push actions if there is a matching or duplicate pull-request action. 
-  check-for-duplicates:
+  # Checks for duplicate actions. Skips push actions if there is a matching or
+  # duplicate pull-request action.
+  checks-for-duplicates:
     runs-on: ubuntu-latest
     # Map a step output to a job output
     outputs:
@@ -22,82 +18,15 @@ jobs:
         with:
           concurrent_skipping: 'same_content'
           skip_after_successful_duplicate: 'true'
-          do_not_skip: '["pull_request", "workflow_dispatch", "schedule"]'
-
-  build-docs:
-    #Continue if check-for-duplicates found no duplicates. Always runs for pull-requests.
-    needs: check-for-duplicates
-    if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
-    runs-on: ubuntu-18.04
-    timeout-minutes: 15
-
-    steps:
-      - name: Install Dependencies
-        run: sudo apt-get install doxygen graphviz -y
-
-      # Check out the cfs bundle
-      - name: Checkout bundle
-        uses: actions/checkout@v2
-        with:
-          repository: nasa/cFS
-          submodules: true
-
-      - name: Checkout submodule
-        uses: actions/checkout@v2
-        with:
-          path: cfe
-
-      - name: Check versions
-        run: git submodule
-
-      # Setup the build system
-      - name: Set up for build
-        run: |
-          cp ./cfe/cmake/Makefile.sample Makefile
-          cp -r ./cfe/cmake/sample_defs sample_defs
-          make prep
-
-      - name: Build Docs
-        run: |
-          make doc > make_doc_stdout.txt 2> make_doc_stderr.txt
-          mv build/docs/detaildesign-warnings.log detaildesign-warnings.log
-
-      # Upload documentation logs as artifacts
-      - name: Archive Documentation Build Logs
-        uses: actions/upload-artifact@v2
-        with:
-          name: cFS Docs Artifacts
-          path: |
-            make_doc_stdout.txt
-            make_doc_stderr.txt
-            detaildesign-warnings.log
-
-      - name: Error Check
-        run: |
-          if [[ -s make_doc_stderr.txt ]]; then
-            cat make_doc_stderr.txt
-            exit -1
-          fi
-
-      - name: Warning Check
-        run: |
-          if [[ -s detaildesign-warnings.log ]]; then
-            cat detaildesign-warnings.log
-            exit -1
-          fi
+          do_not_skip: '["push", "workflow_dispatch", "schedule"]'
 
-  build-usersguide:
-    #Continue if check-for-duplicates found no duplicates. Always runs for pull-requests.
-    needs: check-for-duplicates
-    if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
-    runs-on: ubuntu-18.04
-    timeout-minutes: 15
+  checkout-and-cache:
+    name: Custom checkout and cache for cFS documents
+    needs: checks-for-duplicates
+    if: ${{ needs.checks-for-duplicates.outputs.should_skip != 'true' }}
+    runs-on: ubuntu-latest
 
     steps:
-      - name: Install Dependencies
-        run: sudo apt-get install doxygen graphviz -y
-
-      # Check out the cfs bundle
       - name: Checkout bundle
         uses: actions/checkout@v2
         with:
@@ -109,40 +38,32 @@ jobs:
         with:
           path: cfe
 
-      - name: Check versions
-        run: git submodule
-
-      # Setup the build system
-      - name: Set up for build
-        run: |
-          cp ./cfe/cmake/Makefile.sample Makefile
-          cp -r ./cfe/cmake/sample_defs sample_defs
-          make prep
-
-      - name: Build Usersguide
-        run: |
-          make usersguide > make_usersguide_stdout.txt 2> make_usersguide_stderr.txt
-          mv build/docs/users_guide/cfe-usersguide-warnings.log cfe-usersguide-warnings.log
-
-      - name: Archive Users Guide Build Logs
-        uses: actions/upload-artifact@v2
+      - name: Cache Source and Build
+        id: cache-src-bld
+        uses: actions/cache@v2
         with:
-          name: Users Guide Artifacts
-          path: |
-            make_usersguide_stdout.txt
-            make_usersguide_stderr.txt
-            cfe-usersguide-warnings.log
-
-      - name: Error Check
-        run: |
-          if [[ -s make_usersguide_stderr.txt ]]; then
-            cat make_usersguide_stderr.txt
-            exit -1
-          fi
-
-      - name: Warning Check
-        run: |
-          if [[ -s cfe-usersguide-warnings.log ]]; then
-            cat cfe-usersguide-warnings.log
-            exit -1
-          fi
+          path: /home/runner/work/${{ github.event.repository.name }}/${{ github.event.repository.name }}/*
+          key: cfs-doc-${{ github.run_number }}
+
+  build-cfe-usersguide:
+    needs: checkout-and-cache
+    name: Build and deploy cFS documents
+    uses: nasa/cFS/.github/workflows/build-deploy-doc.yml@main
+    with:
+      target: "[\"cfe-usersguide\"]"
+      cache-key: cfs-doc-${{ github.run_number }}
+      checkout: false
+      buildpdf: ${{ github.event_name == 'push' && contains(github.ref, 'main')}}
+      deploy: ${{ github.event_name == 'push' && contains(github.ref, 'main')}}
+
+  build-mission-doc:
+    needs: checkout-and-cache
+    name: Build and deploy cFS documents
+    #uses: nasa/cFS/.github/workflows/build-deploy-doc.yml
+    uses: skliper/cFS/.github/workflows/build-deploy-doc.yml@fix447-deploy_mission_doc
+    with:
+      target: "[\"mission-doc\"]"
+      cache-key: cfs-doc-${{ github.run_number }}
+      checkout: false
+      deploy: false
+      buildpdf: false # No need for mission pdf within cFE, done at bundle level

cmake/Makefile.sample

@@ -145,14 +145,12 @@ lcov:
 
 doc:
 	$(MAKE) --no-print-directory -C "$(O)" mission-doc
-	@/bin/echo -e "\n\nDetail Design: \nfile://$(CURDIR)/$(O)/docs/detaildesign/html/index.html\n"
 
 usersguide:
 	$(MAKE) --no-print-directory -C "$(O)" cfe-usersguide
-	@/bin/echo -e "\n\ncFE Users Guide: \nfile://$(CURDIR)/$(O)/docs/users_guide/html/index.html\n"
 
 osalguide:
-	$(MAKE) --no-print-directory -C "$(O)" osalguide
+	$(MAKE) --no-print-directory -C "$(O)" osal-apiguide
 
 # Make all the commands that use the build tree depend on a flag file
 # that is used to indicate the prep step has been done.  This way

cmake/cfe-usersguide.doxyfile.in

@@ -13,8 +13,8 @@
 
 # Document specific settings
 PROJECT_NAME           = "Core Flight Executive Users Guide"
-OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/users_guide
-WARN_LOGFILE           = @CMAKE_BINARY_DIR@/docs/users_guide/cfe-usersguide-warnings.log
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/cfe-usersguide
+WARN_LOGFILE           = cfe-usersguide-warnings.log
 
 # For purposes of the user guide, reference the "stock" mission configuration
 # Although missions may override these files, for the users guide we are mainly

cmake/mission-detaildesign.doxyfile.in → cmake/mission-doc.doxyfile.in

@@ -8,11 +8,11 @@
 # Common configuration and default settings
 @INCLUDE               = @MISSION_BINARY_DIR@/docs/cfe-common.doxyfile
 
-# Example detailed design setup
+# Example mission doc design setup
 PROJECT_NAME           = "@MISSION_NAME@"
 PROJECT_BRIEF          = "Core Flight System project built using \"@MISSIONCONFIG@\" configuration"
-OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/detaildesign
-WARN_LOGFILE           = @CMAKE_BINARY_DIR@/docs/detaildesign-warnings.log
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/mission-doc
+WARN_LOGFILE           = mission-doc-warnings.log
 
 # Include mission defs directory
 INPUT                 += @MISSION_DEFS@

cmake/mission_build.cmake

@@ -305,30 +305,28 @@ function(prepare)
     "${CMAKE_BINARY_DIR}/docs/cfe-common.doxyfile"
     @ONLY)
 
-  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/docs/detaildesign")
-  configure_file("${CFE_SOURCE_DIR}/cmake/mission-detaildesign.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/docs/detaildesign/Doxyfile"
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/docs/mission-doc")
+  configure_file("${CFE_SOURCE_DIR}/cmake/mission-doc.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/docs/mission-doc/Doxyfile"
     @ONLY)
   add_custom_target(mission-doc doxygen
-    COMMAND echo "Detail Design: file://${CMAKE_BINARY_DIR}/docs/detaildesign/html/index.html"
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs/detaildesign")
+    COMMAND echo "Detail Design: file://${CMAKE_BINARY_DIR}/docs/mission-doc/html/index.html"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs/mission-doc")
 
-  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/docs/users_guide")
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/docs/cfe-usersguide")
   configure_file("${CFE_SOURCE_DIR}/cmake/cfe-usersguide.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/docs/users_guide/Doxyfile"
+    "${CMAKE_BINARY_DIR}/docs/cfe-usersguide/Doxyfile"
     @ONLY)
   add_custom_target(cfe-usersguide doxygen
-    COMMAND echo "Users Guide: file://${CMAKE_BINARY_DIR}/docs/users_guide/html/index.html"
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs/users_guide")
+    COMMAND echo "Users Guide: file://${CMAKE_BINARY_DIR}/docs/cfe-usersguide/html/index.html"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs/cfe-usersguide")
 
   # OSAL API GUIDE include PUBLIC API
   set(OSAL_API_INCLUDE_DIRECTORIES
     "${osal_MISSION_DIR}/src/os/inc"
     "${CMAKE_BINARY_DIR}/docs"
   )
-  add_subdirectory(${osal_MISSION_DIR}/docs/src ${CMAKE_BINARY_DIR}/docs/osalguide)
-  add_custom_target(osalguide)
-  add_dependencies(osalguide osal-apiguide)
+  add_subdirectory(${osal_MISSION_DIR}/docs/src ${CMAKE_BINARY_DIR}/docs/osal-apiguide)
 
   # Pull in any application-specific mission-scope configuration
   # This may include user configuration files such as cfe_mission_cfg.h,