build_docs.yaml

# This workflow will rebuild YARD docs and update the gh-pages branch.

name: Build Documentation

on:
  push:
    branches: [ main, docs ]

jobs:
  build:
    name: Rebuild YARD docs and update the gh-pages branch
    runs-on: ubuntu-latest

    steps:
      - name: Extract branch name
        run: echo "BRANCH_NAME=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV

      - name: Show branch name
        run: echo "The branch name is $BRANCH_NAME"

      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Ruby and Gems
        uses: ruby/setup-ruby@v1
        env:
          BUNDLE_WITH: documentation
        with:
          bundler-cache: true   # runs 'bundle install' and caches installed gems automatically

      - name: Set git indentity
        run: |
          git config user.name "GitHub Action"
          git config user.email "<>"

      - name: Update YARD html
        run: bundle exec yardoc --output docs/dev

      - name: Update YARD markdown
        run: bundle exec yardoc --template jekyll --format markdown --output docs/tests

      - name: Commit to local branch
        run: |
          git add docs -f
          git commit -m "update docs"

      - name: Checkout changes from docs folder to local gh-pages branch
        run: |
          git checkout gh-pages
          git checkout $BRANCH_NAME -- docs

      - name: Check for changes
        run: |
          if git diff --cached --quiet; then
            echo "git_changes=false" >> $GITHUB_ENV
          else
            echo "git_changes=true" >> $GITHUB_ENV
          fi

      - name: Commit changes in docs folder to local gh-pages branch
        if: env.git_changes == 'true'
        run: |
          git add docs -f
          git commit -m "update docs"

      - name: Push changes
        if: env.git_changes == 'true'
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages