Updating build process and gh-pages fork publications #531
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # | |
| # 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 | |
| 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 |