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
#   https://github.com/action-badges/create-orphan-branch
#
#   Custom workflow for pages deployment
#     
name: Asciidoctor Build Workflow
on:
  # manually run workflow
  workflow_dispatch:
  
  # trigger on PR event against default branch (i.e. main) (will not run publish job)
  pull_request:
    branches: [ main ]
  # Trigger on a push to default branch (i.e. main) (a PR is merged), or when a release is
  
  # published on github. These will run the publish job.
  push:
    branches: [ main ]
  # Trigger when a GitHub release is published.
  release:
    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

jobs: 
  # Job to build cf-conventions.html, cf-conventions.pdf
  build_conventions_and_conformance:
    name: Build cf-conventions and conformance html and pdf
    runs-on: ubuntu-latest
    steps:
    # Check out PR
    - uses: actions/checkout@v4
    # If it is release event, tag for final
    - name: If it is a release add the "final" tag and date timestamp formatting
      if: github.event_name == 'release'
      run: |
        echo "CF_FINAL=True" >> "$GITHUB_ENV"
    # Build cf-conventions.html using the Analog-inc asciidoctor-action
    - name: Make ALL
      uses: Analog-inc/asciidoctor-action@v1
      with:
        shellcommand: 'make all'
    - name: Copy index.html
      run: |
        sudo cp -p .github/gh-pages/index.html build/
    # Update H1 header
    - name: Update H1 header
      run: |
        PATH_REVISION="${GITHUB_REPOSITORY}/${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}@${GITHUB_SHA:0:7}"
        sudo sed -i s/Latest/"${PATH_REVISION//\//\\/}"/ build/index.html;
    # Upload artifact containing cf-conventions.html, cf-conventions.pdf
    - name: Save cf-conventions and conformance docs
      uses: actions/upload-artifact@v4
      with:
        name: convention_and_conformance_docs
        path: build/
  # Use artifacts from the build_conventions, build_conformance, and
  # images_artifact jobs to update the gh-pages branch. The location of the
  # files to be updated depend on whether the job it triggered from a PR merge
  # into main (files in the base directory are updated), or if the job is
  # triggered by the publication of a release on github (new files are created
  # in a directory named after the release name).
  publish:
    name: Release cf-conventions and conformance html and pdf
    # Do not run on pull requests
    if: github.event_name != 'pull_request'
    # Wait for the build artifacts to become available
    needs: [build_conventions_and_conformance]
    
#    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
#    permissions:
#      pages: write      # to deploy to Pages
#      id-token: write   # to verify the deployment originates from an appropriate source

#    # Deploy to the github-pages environment
#    environment:
#      name: github-pages
#      url: ${{ steps.deployment.outputs.page_url }}
    
    runs-on: ubuntu-latest
    steps:
      # Checkout repo
      - uses: actions/checkout@v4
      # create a new orphan branch if a branch with the given name does not already exist
      - name: Create Orphan Branch
        uses: action-badges/create-orphan-branch@0.1.1
        with:
          branch-name: 'gh-pages'
      # Checkout gh-pages branch
      - uses: actions/checkout@v4
        with:
          ref: 'gh-pages'
      - name: Add .nojekyll file if it doesn't exist
        run: |
          if [ ! -f .nojekyll ]; then
            touch .nojekyll
          fi
      # Will new docs go into root, or into a directory named after the
      # release?
      - name: Determine where the new documents should live
        run: |
          if [[ ${{ github.event_name }} == 'release' ]]; then
            echo "TARGET_DIR=releases/${GITHUB_REF_NAME}" >> "$GITHUB_ENV"
          else
            echo "TARGET_DIR=${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}" >> "$GITHUB_ENV"
          fi
      # Obtain the build artifacts from the previous jobs and place them in the
      # build/ directory
      - uses: actions/download-artifact@v4
        with:
          name: convention_and_conformance_docs
          path: build/
      # If we are doing a release, we need to create the release directory
      - name: Make release directory
        run: mkdir -p ${{ env.TARGET_DIR }}
      # If we are not doing a release, let's clean out the previous images
      # directory in the root directory (OLD TO BE DEPRECATED)
      - name: Remove old images directory
        run: sudo rm -rf ${{ env.TARGET_DIR }}/images
      - name: Copy conventions and conformance documents
        run: |
          cp -p build/cf-conventions.html ${{ env.TARGET_DIR }}/
          cp -p build/cf-conventions.pdf ${{ env.TARGET_DIR }}/
          cp -p build/conformance.html ${{ env.TARGET_DIR }}/
          cp -p build/conformance.pdf ${{ env.TARGET_DIR }}/
          cp -p build/index.html ${{ env.TARGET_DIR }}/
      # Remove the directory that held the artifacts so that it does not get
      # committed to the gh-pages branch
      - name: Remove artifact directory
        run: rm -rf build/
      # Update root index.html: tree directories, excluding empty ones 
      - name: Update root index.html
        run: tree -T ${GITHUB_REPOSITORY} --dirsfirst --prune --noreport -I index.html -H . -o index.html
      # Stage all changed files to git
      - name: Add all changes to git
        run: git add --all
      # Configure git to use the built-in repo credentials, commit changes, and
      # push to the gh-pages branch
      - name: Commit changes and push to gh-pages branch
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git commit -m "Auto-generated from ${GITHUB_REPOSITORY}@${GITHUB_SHA}"
          git push