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:
  # manually run workflow
  workflow_dispatch:
  # trigger on PR event against main (will not run publish job)
  pull_request:
    branches: [ main ]
  # Trigger on a push to 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
jobs:
  # Job to build cf-conventions.html, cf-conventions.pdf
  build_conventions:
    name: Build cf-conventions 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: Build cf-conventions.html
      uses: Analog-inc/asciidoctor-action@v1
      with:
        shellcommand: 'make conventions-html'
    # Build cf-conventions.pdf using the Analog-inc asciidoctor-action
    - name: Build cf-conventions.pdf
      uses: Analog-inc/asciidoctor-action@v1
      with:
        shellcommand: 'make conventions-pdf'
    # Upload artifact containing cf-conventions.html, cf-conventions.pdf
    - name: Save cf-conventions doc preview
      uses: actions/upload-artifact@v4
      with:
        name: conventions_docs
        path: conventions_build/
  # Job to build conformance.html, conformance.pdf
  build_conformance:
    name: Build conformance html and pdf
    runs-on: ubuntu-latest
    steps:
    # Checkout PR
    - uses: actions/checkout@v4
    # Create build directory
    - run: mkdir conformance_build
    # 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 conformance.html using the Analog-inc asciidoctor-action
    - name: Build conformance.html
      uses: Analog-inc/asciidoctor-action@v1
      with:
        shellcommand: 'make conformance-html'
    # Build conformance.pdf using the Analog-inc asciidoctor-action
    - name: Build conformance.pdf
      uses: Analog-inc/asciidoctor-action@v1
      with:
        shellcommand: 'make conformance-pdf'
    # Upload artifact containing conformance.html, conformance.pdf
    - name: Save conformance doc preview
      uses: actions/upload-artifact@v4
      with:
        name: conformance_docs
        path: conformance_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 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, build_conformance]
    runs-on: ubuntu-latest
    steps:
      # Checkout gh-pages branch
      - uses: actions/checkout@v4
        with:
          ref: 'gh-pages'
      # 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
            # ${GITHUB_REF##*/} -> turns refs/tags/vM.m.p into vM.m.p
            echo "TARGET_DIR=${GITHUB_REF##*/}" >> "$GITHUB_ENV"
          else
            echo "TARGET_DIR=." >> "$GITHUB_ENV"
          fi
      # Obtain the build artifacts from the previous jobs and place them in the
      # build/ directory
      - uses: actions/download-artifact@v4
        with:
          path: build/
      # If we are doing a release, we need to create the release directory
      - name: Make release directory
        if: github.event_name == 'release'
        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
      - name: Remove old images directory
        if: github.event_name != 'release'
        run: rm -rf ${{ env.TARGET_DIR }}/images
      - name: Copy conventions and conformance documents
        run: |
          cp build/conventions_docs/cf-conventions.html ${{ env.TARGET_DIR }}/
          cp build/conventions_docs/cf-conventions.pdf ${{ env.TARGET_DIR }}/
          cp build/conformance_docs/conformance.html ${{ env.TARGET_DIR }}/
          cp build/conformance_docs/conformance.pdf ${{ 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/
      # If we are doing a release, update the index.html file to reflect the new
      # latest release version.
      - name: Update release index.html to point to new release
        if: github.event_name == 'release'
        run: |
          sed s/Latest/"${GITHUB_REF##*/}"/ index.html > ${{ env.TARGET_DIR }}/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