build-documentation.yml

name: cFS Documentation and Guides Script

on:
  push:
  pull_request:
  workflow_dispatch:
  schedule:
    # 10:45 PM UTC every Sunday
    - cron:  '45 22 * * 0'

jobs:
  # Checks for duplicate actions. Skips push actions if there is a matching or
  # duplicate pull-request action.
  checks-for-duplicates:
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || '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: '["pull_request", "workflow_dispatch", "schedule"]'

  checkout-and-cache:
    name: Custom checkout and cache for cFS documents
    needs: checks-for-duplicates
    if: ${{ needs.checks-for-duplicates.outputs.should_skip != 'true' || contains(github.ref, 'main') }}
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || 'ubuntu-latest' }}

    steps:
      - name: Checkout bundle
        uses: actions/checkout@v3
        with:
          repository: arielswalker/cFS
          submodules: true

      - name: Checkout submodule
        uses: actions/checkout@v3
        with:
          path: cfe

      - name: Cache Source and Build
        id: cache-src-bld
        uses: actions/cache@v3
        with:
          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 cFE Docs    
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || 'ubuntu-latest' }}
    env:
      TARGET: '["cfe-usersguide"]'
      CACHE_KEY: "cfs-doc-${{ github.run_number }}"
      DEPLOY: "false" # Note can't use cache with deploy, deploy in following job instead
      BUILD_PDF: "${{ github.event_name == 'push' && contains(github.ref, 'main')}}" 
      APP_NAME: ""
      NEEDS_OSAL_API: "true"
      
    steps:
      - name: Get cache if supplied
        id: cache-src-bld
        if: ${{ env.CACHE_KEY != '' }}
        uses: actions/cache@v4
        with:
          path: /home/runner/work/${{ github.event.repository.name }}/${{ github.event.repository.name }}/*
          key: ${{ env.CACHE_KEY }}

      - name: Checkout Repo
        if: ${{ env.APP_NAME != '' }}
        uses: actions/checkout@v4
        with:
          path: apps/${{ env.APP_NAME}}
          
      - name: Run Build Document Script
        run: |          
          chmod +x ./.github/scripts/build-deploy-doc.sh
          ./.github/scripts/build-deploy-doc.sh "$TARGET" "$CACHE_KEY" "$DEPLOY" "$BUILD_PDF" "$APP_NAME" "$NEEDS_OSAL_API"

      - name: Archive Document Build Logs
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.TARGET }}_doc_build_logs
          path: |
            ${{ env.TARGET }}_stdout.txt
            ${{ env.TARGET }}_stderr.txt
            ${{ env.TARGET }}-warnings.log
            ${{ env.TARGET }}.pdf
            
  build-mission-doc:
    needs: checkout-and-cache
    name: Build Mission Doc  
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || 'ubuntu-latest' }}
    env:
      TARGET: '["mission-doc"]'
      CACHE_KEY: "cfs-doc-${{ github.run_number }}"
      DEPLOY: "false" 
      BUILD_PDF: "false" # No need for mission pdf within cFE, done at bundle level
      APP_NAME: ""
      NEEDS_OSAL_API: "true"
      
    steps:
      - name: Get cache if supplied
        id: cache-src-bld
        if: ${{ env.CACHE_KEY != '' }}
        uses: actions/cache@v4
        with:
          path: /home/runner/work/${{ github.event.repository.name }}/${{ github.event.repository.name }}/*
          key: ${{ env.CACHE_KEY }}

      - name: Checkout Bundle Main
        uses: actions/checkout@v4
        with:
          submodules: true
          repository: arielswalker/cFS

      - name: Checkout Repo
        if: ${{ env.APP_NAME != '' }}
        uses: actions/checkout@v4
        with:
          path: apps/${{ env.APP_NAME}}
          
      - name: Run Build Document Script
        run: |          
          chmod +x ./.github/scripts/build-deploy-doc.sh
          ./.github/scripts/build-deploy-doc.sh "$TARGET" "$CACHE_KEY" "$DEPLOY" "$BUILD_PDF" "$APP_NAME" "$NEEDS_OSAL_API"

      - name: Archive Document Build Logs
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.TARGET }}_doc_build_logs
          path: |
            ${{ env.TARGET }}_stdout.txt
            ${{ env.TARGET }}_stderr.txt
            ${{ env.TARGET }}-warnings.log
            ${{ env.TARGET }}.pdf
                
  deploy-documentation:
    needs: build-cfe-usersguide
    if: ${{ github.event_name == 'push' && contains(github.ref, 'main')}}
    name: Deploy documentation to gh-pages
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || 'ubuntu-latest' }}

    steps:
      - uses: actions/checkout@v3

      - uses: actions/download-artifact@v3

      - name: Display structure of downloaded files
        run: ls -R

      - name: Move pdfs to deployment directory
        run: mkdir deploy; mv */*.pdf deploy

      - name: Deploy to GitHub
        uses: JamesIves/github-pages-deploy-action@3.7.1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: deploy
          SINGLE_COMMIT: true