Updating build process and gh-pages fork publications

.github/workflows/build_and_deploy_docs.yml

@@ -0,0 +1,216 @@
+#
+# 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:
+  workflow_dispatch:  # Manual trigger
+  pull_request:       # On pull request
+  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 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: 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
+          # Determine target directory based on the event type
+          if [[ ${{ github.event_name }} == 'release' ]]; then
+            echo "TARGET_DIR=release/${GITHUB_REF_NAME}" >> $GITHUB_ENV
+          elif [[ ${{ github.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