From 34cdb6d6f20b05b180fab9f233998c586d3c083e Mon Sep 17 00:00:00 2001 From: Jacob Hageman Date: Wed, 13 Apr 2022 06:29:38 -0600 Subject: [PATCH] Fix #447 #455, Use reusable doc workflow to add mission-doc pdf deploy --- .github/workflows/build-deploy-doc.yml | 153 ++++++++++++++++ .github/workflows/build-documentation.yml | 208 ++++------------------ 2 files changed, 184 insertions(+), 177 deletions(-) create mode 100644 .github/workflows/build-deploy-doc.yml diff --git a/.github/workflows/build-deploy-doc.yml b/.github/workflows/build-deploy-doc.yml new file mode 100644 index 000000000..fa0ca92f9 --- /dev/null +++ b/.github/workflows/build-deploy-doc.yml @@ -0,0 +1,153 @@ +name: Build Document + +on: + workflow_call: + inputs: + # Required + target: + description: Document target name(s) as stringified JSON matrix list # Matrix example "[\"x\", \"y\"]" + type: string + required: true + # Optional + app-name: + description: Application name, leave blank if using cache + type: string + required: false + default: '' + cache-key: + description: Cache key to use + type: string + required: false + default: '' + buildpdf: + description: Build the PDF + type: boolean + required: false + default: true + deploy: + description: Deploy archived PDF to gh-pages + type: boolean + required: false + default: true + +jobs: + # 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: + should_skip: ${{ steps.skip_check.outputs.should_skip }} + steps: + - id: skip_check + uses: fkirc/skip-duplicate-actions@master + with: + concurrent_skipping: 'same_content' + skip_after_successful_duplicate: 'true' + do_not_skip: '["push", "workflow_dispatch", "schedule"]' + + build-doc: + needs: checks-for-duplicates + if: ${{ needs.checks-for-duplicates.outputs.should_skip != 'true' }} + name: Build Documentation + runs-on: ubuntu-18.04 + + strategy: + fail-fast: false + matrix: + target: ${{ fromJson(inputs.target) }} + + steps: + - name: Get cache if supplied + id: cache-src-bld + if: ${{ inputs.cache-key != '' }} + uses: actions/cache@v2 + with: + path: /home/runner/work/${{ github.event.repository.name }}/${{ github.event.repository.name }}/* + key: ${{ inputs.cache-key }} + + - name: Checkout Bundle Main + if: ${{ inputs.app-name != '' }} + uses: actions/checkout@v2 + with: + submodules: true + repository: nasa/cFS + + - name: Checkout Repo + if: ${{ inputs.app-name != '' }} + uses: actions/checkout@v2 + with: + path: apps/${{ inputs.app-name }} + + - name: Copy Files + run: | + cp ./cfe/cmake/Makefile.sample Makefile + cp -r ./cfe/cmake/sample_defs sample_defs + + - name: Add Repo To Build + if: ${{ inputs.checkout == true }} + run: sed -i '/list(APPEND MISSION_GLOBAL_APPLIST/a list(APPEND MISSION_GLOBAL_APPLIST repo)' sample_defs/targets.cmake + + - name: Make Prep + run: make prep + + - name: Install Doxygen Dependencies + run: sudo apt-get install doxygen graphviz -y + + - name: Install PDF Generation Dependencies + if: ${{ inputs.buildpdf == true }} + run: | + sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra + + - name: Build Document + run: | + make -C build ${{ matrix.target }} > ${{ matrix.target }}_stdout.txt 2> ${{ matrix.target }}_stderr.txt + mv build/docs/${{ matrix.target }}/${{ matrix.target }}-warnings.log . + + - name: Archive Document Build Logs + uses: actions/upload-artifact@v2 + with: + name: ${{ matrix.target }}_doc_build_logs + path: | + ${{ matrix.target }}_stdout.txt + ${{ matrix.target }}_stderr.txt + ${{ matrix.target }}-warnings.log + + - name: Check For Document Build Errors + run: | + if [[ -s ${{ matrix.target }}_stderr.txt ]]; then + cat ${{ matrix.target }}_stderr.txt + exit -1 + fi + + - name: Check For Document Warnings + run: | + if [[ -s ${{ matrix.target }}-warnings.log ]]; then + cat ${{ matrix.target }}-warnings.log + exit -1 + fi + + - name: Generate PDF + if: ${{ inputs.buildpdf == true }} + run: | + make -C ./build/docs/${{ matrix.target }}/latex + mkdir deploy + mv ./build/docs/${{ matrix.target }}/latex/refman.pdf ./deploy/${{ matrix.target }}.pdf + # Could add pandoc and convert to github markdown + # pandoc ${{ matrix.target }}.pdf -t gfm + + - name: Archive PDF + if: ${{ inputs.buildpdf == true }} + uses: actions/upload-artifact@v2 + with: + name: ${{ matrix.target }}_pdf + path: ./deploy/${{ matrix.target }}.pdf + + - name: Deploy to GitHub + if: ${{ inputs.deploy == true }} + uses: JamesIves/github-pages-deploy-action@3.7.1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages + FOLDER: deploy + SINGLE_COMMIT: true diff --git a/.github/workflows/build-documentation.yml b/.github/workflows/build-documentation.yml index 3bb64c35d..242f27516 100644 --- a/.github/workflows/build-documentation.yml +++ b/.github/workflows/build-documentation.yml @@ -1,14 +1,9 @@ -name: Documentation and Guides +name: cFS Documentation and Guides -# Run every time a new commit pushed to main or for pull requests on: push: pull_request: -env: - SIMULATION: native - REPO_NAME: ${{ github.event.repository.name }} - jobs: # Checks for duplicate actions. Skips push actions if there is a matching or # duplicate pull-request action. @@ -25,197 +20,56 @@ jobs: skip_after_successful_duplicate: 'true' do_not_skip: '["push", "workflow_dispatch", "schedule"]' - build-docs: - # Continue if checks-for-duplicates found no duplicates. Always runs for - # pull-requests. + checkout-and-cache: + name: Custom checkout and cache for cFS documents needs: checks-for-duplicates if: ${{ needs.checks-for-duplicates.outputs.should_skip != 'true' }} - name: cFE Documentation - runs-on: ubuntu-18.04 + runs-on: ubuntu-latest steps: - - name: Install Dependencies - run: sudo apt-get install doxygen graphviz -y - - # Check out the cfs bundle - name: Checkout code uses: actions/checkout@v2 with: submodules: true - # Prepare build "recipes" - - name: Copy Files - run: | - cp ./cfe/cmake/Makefile.sample Makefile - cp -r ./cfe/cmake/sample_defs sample_defs - # Setup the build system - - name: Make Prep - run: 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 + - name: Cache Source and Build + id: cache-src-bld + uses: actions/cache@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 - - build: - needs: checks-for-duplicates - if: ${{ needs.checks-for-duplicates.outputs.should_skip != 'true' }} - name: Build OSAL & Users Guide - runs-on: ubuntu-18.04 + path: /home/runner/work/${{ github.event.repository.name }}/${{ github.event.repository.name }}/* + key: cfs-doc-${{ github.run_number }} + + build-cfs-documentation: + needs: checkout-and-cache + name: Build and deploy cFS documents + uses: nasa/cFS/.github/workflows/build-deploy-doc.yml@main + with: + target: "[\"cfe-usersguide\", \"osal-apiguide\", \"mission-doc\"]" + cache-key: cfs-doc-${{ github.run_number }} + checkout: false + deploy: false + + deploy-documentation: + needs: build-cfs-documentation + if: ${{ github.event_name == 'push' && contains(github.ref, 'main')}} + name: Deploy documentation to gh-pages + runs-on: ubuntu-latest steps: - # Checks out a copy of your repository on the ubuntu-latest machine - - name: Checkout code - uses: actions/checkout@v2 - with: - submodules: true - persist-credentials: false + - uses: actions/checkout@v2 - # Setup the build system - - name: Copy Files - run: | - cp ./cfe/cmake/Makefile.sample Makefile - cp -r ./cfe/cmake/sample_defs sample_defs - - # Setup the build system - - name: Make Prep - run: make prep + - uses: actions/download-artifact@v3 - - name: Install Dependencies - run: sudo apt-get install doxygen graphviz -y + - name: Display structure of downloaded files + run: ls -R - - name: Build OSAL Guide - run: | - make osalguide > make_osalguide_stdout.txt 2> make_osalguide_stderr.txt - mv build/docs/osalguide/osal-apiguide-warnings.log osal-apiguide-warnings.log - - - name: Archive Osal Guide Build Logs - uses: actions/upload-artifact@v2 - with: - name: OSAL Guide Artifacts - path: | - make_osalguide_stdout.txt - make_osalguide_stderr.txt - osal-apiguide-warnings.log - - - name: Check for Errors - run: | - if [[ -s make_osalguide_stderr.txt ]]; then - cat make_osalguide_stderr.txt - exit -1 - fi - - - name: Check for Warnings - run: | - if [[ -s osal-apiguide-warnings.log ]]; then - cat osal-apiguide-warnings.log - exit -1 - fi - - - name: Install Dependencies - if: ${{ github.event_name == 'push' && contains(github.ref, 'main')}} - run: | - sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra - - - name: Generate PDF - if: ${{ github.event_name == 'push' && contains(github.ref, 'main')}} - run: | - mkdir deploy - cd ./build/docs/osalguide/latex - make > build.txt - mv refman.pdf $GITHUB_WORKSPACE/deploy/OSAL_Users_Guide.pdf - # Could add pandoc and convert to github markdown - # pandoc CFE_Users_Guide.pdf -t gfm - - - 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: Move pdfs to deployment directory + run: mkdir deploy; mv */*.pdf deploy - - name: Archive Users Guide Build Logs - uses: actions/upload-artifact@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 - - - name: Generate PDF - if: ${{ github.event_name == 'push' && contains(github.ref, 'main')}} - run: | - set -x - cd ./build/docs/users_guide/latex - make > build.txt - mv refman.pdf $GITHUB_WORKSPACE/deploy/cFE_Users_Guide.pdf - # Could add pandoc and convert to github markdown - # pandoc CFE_Users_Guide.pdf -t gfm - - - name: Cache cFS Build Environment for usersguide - id: cache-guide - uses: actions/cache@v2 - with: - path: /home/runner/work/${{ env.REPO_NAME }}/${{ env.REPO_NAME }}/deploy/* - key: guide-buildnum-${{ github.run_number }} - - deploy: - needs: build - name: Deploy OSAL & Users Guide - runs-on: ubuntu-18.04 - if: ${{ github.event_name == 'push' && contains(github.ref, 'main')}} - - steps: - - name: Cache cFS Build Environment for osalguide - id: cache-guide - uses: actions/cache@v2 - with: - path: /home/runner/work/${{ env.REPO_NAME }}/${{ env.REPO_NAME }}/deploy/* - key: guide-buildnum-${{ github.run_number }} - - name: Deploy to GitHub uses: JamesIves/github-pages-deploy-action@3.7.1 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} BRANCH: gh-pages FOLDER: deploy - CLEAN: false SINGLE_COMMIT: true -