adoc_build.yml

#
# GitHub Actions Workflow for building and publishing the CF conventions and
# conformance docs.
#
# Pull request events against the main branch trigger jobs to build the
# documents. If successful, the resulting html and pdf files are uploaded as
# artifacts to make it easier to preview the impacts of a PR on the
# documentation.
#
# When a PR is accepted and merged into main, the documents are built and
# published to the root directory of the gh-pages branch.
#
# When a GitHub release is published, the documents are built and published to
# on the gh-pages branch in a directory named after the release (e.g. v1.9.0/).
#
# 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

name: Asciidoctor Build Workflow
on:
  workflow_dispatch:  # Manual trigger
  pull_request:       # On pull request to main
    branches: [main]
  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
    
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
  
      - name: Set Release Tag and Date
        if: github.event_name == 'release'
        run: |
          echo "CF_FINAL=True" >> $GITHUB_ENV
  
      - name: Build Documentation
        uses: Analog-inc/asciidoctor-action@v1
        with:
          shellcommand: 'make all'
  
      - name: Prepare and Update Index Page
        run: |
          sudo cp -p .github/gh-pages/index.html build/
          PATH_REVISION="${GITHUB_REPOSITORY}/${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}@${GITHUB_SHA:0:7}"
          sudo sed -i "s/Latest/${PATH_REVISION//\//\\/}/" build/index.html
  
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documentation_artifacts
          path: build/
          

  # Job to publish documentation to GitHub Pages
  publish_docs:
    name: Publish Documentation
    runs-on: ubuntu-latest
    needs: build_docs
    if: github.event_name != 'pull_request'
   
    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
          # Determine target directory based on the event type
          if [[ ${{ github.event_name }} == 'release' ]]; then
            echo "TARGET_DIR=releases/${GITHUB_REF_NAME}" | sed 's/[^a-zA-Z0-9._-]/_/g' >> $GITHUB_ENV
          else
            echo "TARGET_DIR=${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}" | sed 's/[^a-zA-Z0-9._-]/_/g' >> $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
        run: |
          cd gh-pages
          mkdir -p ${{ env.TARGET_DIR }}
          cp -p build/*.html ${{ env.TARGET_DIR }}/
          cp -p build/*.pdf ${{ env.TARGET_DIR }}/
          rm -rf build/ 
          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