build_and_deploy_docs.yml

#
# GitHub Actions Workflow for building and publishing the CF conventions and
# conformance docs.
#
# For more information on the actions used in this workflow, please see:
#   https://github.com/actions/checkout
#   https://github.com/Analog-inc/asciidoctor-action
#   https://github.com/actions/upload-artifact
#   https://github.com/actions/download-artifact
#   https://github.com/marocchino/sticky-pull-request-comment

name: Asciidoctor Build Workflow
on:
  pull_request:       # On pull request
  workflow_dispatch:
    inputs:
      set_final_tag:
        description: "Set Final Tag"
        required: false
        default: "false"
  push:               # On push any branch (excluding gh-pages)
    branches-ignore: [gh-pages]
  release:            # On release published
    types:
      - published

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  DESIRED_BRANCH: "gh-pages"      # Branch to use for GitHub Pages
  DESIRED_PATH: "/"               # Path to use for GitHub Pages
  DESIRED_BUILD_TYPE: "legacy"    # Build type for GitHub Pages
  GH_TOKEN: ${{ github.token }}

jobs: 
  # Job to build documents
  build_docs:
    name: Build Documentation
    runs-on: ubuntu-latest
    if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
  
      - name: Set Final Tag
        if: ${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' && inputs.set_final_tag == 'true' }}
        run: |
          echo "CF_FINAL=True" >> $GITHUB_ENV
  
      - name: Build Documentation
        uses: Analog-inc/asciidoctor-action@v1
        with:
          shellcommand: 'make all'
  
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documentation_artifacts
          path: build/

      - name: Output Artifact Link for PR
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          echo "Artifacts for this PR can be downloaded from the following link:"
          echo "https://${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/"
          echo "::notice::[Download Artifacts](https://${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/)"

  # Job to publish documentation to GitHub Pages and as assests on release page
  publish_docs:
    name: Publish Documentation
    runs-on: ubuntu-latest
    needs: build_docs
    if: ${{ github.event_name != 'pull_request' }} # Skip this job if the event is a PR
    steps:
      - name: Verify Pre-installed Tools
        run: |
          jq --version
          tree --version
          gh --version

      - name: Checkout Repository
        uses: actions/checkout@v4
 
      - name: Check and Create GH Pages Branch
        run: |
          if ! git ls-remote --exit-code origin gh-pages > /dev/null; then
            echo "Creating the $DESIRED_BRANCH branch..."
            git checkout --orphan $DESIRED_BRANCH
            git rm -rf . || true
            echo "# GitHub Pages" > index.html
            git add index.html
            git commit -m "Initialize $DESIRED_BRANCH branch"
            git push origin $DESIRED_BRANCH
          else
            echo "The $DESIRED_BRANCH branch already exists."
          fi

      - name: Enforce GitHub Pages Configuration
        run: |
          # Fetch current GitHub Pages configuration
          API_RESPONSE=$(gh api repos/${{ github.repository }}/pages || echo "{}")
      
          # Extract current configuration
          IS_ENABLED=$(echo "$API_RESPONSE" | jq -r '.source // empty')
          BUILD_TYPE=$(echo "$API_RESPONSE" | jq -r '.build_type // empty')
          SOURCE_BRANCH=$(echo "$API_RESPONSE" | jq -r '.source.branch // empty')
          SOURCE_PATH=$(echo "$API_RESPONSE" | jq -r '.source.path // empty')
      
          # Enforce configuration if any setting is incorrect or GitHub Pages is not enabled
          if [[ -z "$IS_ENABLED" ]] || [[ "$BUILD_TYPE" != "$DESIRED_BUILD_TYPE" ]] || [[ "$SOURCE_BRANCH" != "$DESIRED_BRANCH" ]] || [[ "$SOURCE_PATH" != "$DESIRED_PATH" ]]; then
            echo "Enforcing GitHub Pages configuration..."
            gh api repos/${{ github.repository }}/pages \
              --method POST \
               --input - <<< "{\"source\":{\"branch\":\"$DESIRED_BRANCH\",\"path\":\"$DESIRED_PATH\"}, \"build_type\":\"$DESIRED_BUILD_TYPE\"}"
            echo "GitHub Pages has been configured: Branch='${DESIRED_BRANCH}', Path='${DESIRED_PATH}', Build Type='${DESIRED_BUILD_TYPE}'."
          else
            echo "GitHub Pages is already configured correctly: Branch='${DESIRED_BRANCH}', Path='${DESIRED_PATH}', Build Type='${DESIRED_BUILD_TYPE}'."
          fi
          
      - name: Checkout gh-pages Branch into Subdirectory
        uses: actions/checkout@v4
        with:
          repository: ${{ github.repository }}
          ref:  ${{ env.DESIRED_BRANCH }}
          path: gh-pages
      
      - name: Determine Target Directory and Add .nojekyll
        run: |
          cd gh-pages
          # Ensure .nojekyll exists
          [ ! -f .nojekyll ] && touch .nojekyll
          
          FINAL_TAG_INPUT="${{ github.event.inputs.set_final_tag || 'false' }}"
          EVENT_NAME="${{ github.event_name }}" 

          # Determine target directory based on the event type
          if [[ "$EVENT_NAME" == "workflow_dispatch" && "$FINAL_TAG_INPUT" == "true" ]]; then
            echo "TARGET_DIR=final-preview/${GITHUB_REF_NAME}" >> $GITHUB_ENV
          elif [[ "$EVENT_NAME" == 'release' ]]; then
            echo "TARGET_DIR=release/${GITHUB_REF_NAME}" >> $GITHUB_ENV
          elif [[ "$EVENT_NAME" == 'pull_request' ]]; then
            PR_NUMBER=${{ github.event.pull_request.number }}
            echo "TARGET_DIR=pr-preview/${PR_NUMBER}" >> $GITHUB_ENV
          elif [[ ${{ github.ref_name }} == '${{ github.event.repository.default_branch }}' ]]; then
            echo "TARGET_DIR=./" >> $GITHUB_ENV
          else
            echo "TARGET_DIR=${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}" >> $GITHUB_ENV
          fi

      - name: Download Artifacts
        uses: actions/download-artifact@v4
        with:
          name: documentation_artifacts
          path: gh-pages/build/

      - name: Verify Build Artifacts
        run: |
          cd gh-pages
          if [ ! "$(ls -A build)" ]; then
            echo "Build artifacts are missing!" >&2
            exit 1
          fi
        
      - name: Publish Documentation
        if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}
        run: |
          cd gh-pages
          mkdir -p ${{ env.TARGET_DIR }}
          cp -p build/* ${{ env.TARGET_DIR }}/
          rm -rf build/ 

      - name: Prepare and Update Index Page
        run: |
          cd gh-pages
          sudo cp -p ../.github/gh-pages/index.html ${{ env.TARGET_DIR }}/
          
          COMMIT_DATE=$(git show -s --format=%cd --date=format:'%Y-%m-%dT%H:%M:%SZ')

          if [[ "${GITHUB_REF_NAME}" != "${{ github.event.repository.default_branch }}" ]]; then
            PATH_REVISION="${GITHUB_REPOSITORY}/${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}@${GITHUB_SHA:0:7}"
            sudo sed -i "s/Latest/${PATH_REVISION//\//\\/}/" ${{ env.TARGET_DIR }}/index.html
          else
            echo "Push is to the default branch; Latest build"
          fi
  
      - name: Cleanup PR Artifacts
        if: ${{ github.event_name == 'pull_request' && github.event.action == 'closed' }}
        run: |
          cd gh-pages
          rm -rf ${{ env.TARGET_DIR }}

      - name: Build Index Tree
        run: |
            cd gh-pages
            tree -T "${GITHUB_REPOSITORY}" --dirsfirst --prune --noreport \
              -I "index.html|README.md" -H . -o index.html
  
      - name: Commit and Push Changes
        run: |
          cd gh-pages
          git add --all
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git commit -m "Update documentation from ${GITHUB_REPOSITORY}@${GITHUB_SHA}" || echo "No changes to commit; skipping push."
          git push

      - name: Upload Documentation files as Release Asset
        if: github.event_name == 'release'
        run: |
          export TARGET_DIR=${{ env.TARGET_DIR }}
          gh release upload ${{ github.event.release.tag_name }} \
            gh-pages/${TARGET_DIR}/cf-conventions.html \
            gh-pages/${TARGET_DIR}/cf-conventions.pdf  \
            gh-pages/${TARGET_DIR}/conformance.html    \
            gh-pages/${TARGET_DIR}/conformance.pdf     \
            --clobber