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-docs:
    needs: checkout-and-cache
    name: Build cFE and Mission Docs
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || 'ubuntu-latest' }}
    strategy:
      matrix:
        target: ['["cfe-usersguide"]', '["mission-doc"]']
    env:
      CACHE_KEY: "cfs-doc-${{ github.run_number }}"
      DEPLOY: "false"
      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: Set Build PDF Variable
        id: set-build-pdf
        run: |
          if [ "${{ matrix.target }}" == "cfe-usersguide" ]; then
            echo "BUILD_PDF=${{ github.event_name == 'push' && contains(github.ref, 'main') }}" >> $GITHUB_ENV
          else
            echo "BUILD_PDF=false" >> $GITHUB_ENV
          fi
          
      - name: Set Target Variable
        id: set-target
        run: |
          if [ "${{ matrix.target }}" == "cfe-usersguide" ]; then
            echo "TARGET_JSON='["cfe-usersguide"]'" >> $GITHUB_ENV
          elif [ "${{ matrix.target }}" == "mission-doc" ]; then
            echo "TARGET_JSON='["mission-doc"]'" >> $GITHUB_ENV
          fi

      - name: Run Build Document Script
        run: |
          chmod +x ./.github/scripts/build-deploy-doc.sh
          ./.github/scripts/build-deploy-doc.sh "${TARGET_JSON}" "$CACHE_KEY" "$DEPLOY" "$BUILD_PDF" "$APP_NAME" "$NEEDS_OSAL_API"

      - name: Archive Document Build Logs
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.target }}_doc_build_logs
          path: |
            ${{ matrix.target }}_stdout.txt
            ${{ matrix.target }}_stderr.txt
            ${{ matrix.target }}-warnings.log
            ${{ matrix.target }}.pdf

  deploy-documentation:
    needs: build-docs
    if: ${{ github.event_name == 'push' && contains(github.ref, 'main') && needs.build-docs.outputs.DEPLOY == 'true' }}
    name: Deploy documentation to gh-pages
    runs-on: ${{ github.repository_owner == 'cFS' && 'linux' || 'ubuntu-latest' }}

    steps:
      - name: Checkout bundle
        uses: actions/checkout@v3

      - name: Download cFE Users Guide Artifact
        uses: actions/download-artifact@v3
        with:
          name: cfe-usersguide_doc_build_logs
          path: ./ 

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

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

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