deploy-to-gh-pages.yml

# This GitHub Actions workflow creates a production build of the website and deploys it to GitHub Pages.
# Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
name: Build and deploy to GitHub Pages

on:
  push: { branches: [ main ] }
  workflow_dispatch: { }

# Reference: https://docs.github.com/en/actions/using-jobs/using-concurrency
concurrency:
  group: github-pages
  cancel-in-progress: true

jobs:
  # Use existing workflows to compile the legacy home, home, Runtime, and workflow documentation.
  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow
  compile-legacy-home-docs:
    name: Compile legacy home docs
    uses: ./.github/workflows/compile-legacy-home-docs.yml
  compile-home-docs:
    name: Compile home docs
    uses: ./.github/workflows/compile-home-docs.yml
  fetch-and-compile-runtime-docs:
    name: Fetch and compile Runtime docs
    uses: ./.github/workflows/fetch-and-compile-runtime-docs.yml
  fetch-and-compile-workflow-docs:
    name: Fetch and compile workflow docs
    uses: ./.github/workflows/fetch-and-compile-workflow-docs.yml

  build:
    name: Compile main website
    # This job depends upon other jobs succeeding.
    # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds
    needs:
      - compile-legacy-home-docs
      - compile-home-docs
      - fetch-and-compile-runtime-docs
      - fetch-and-compile-workflow-docs
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Check out commit  # Docs: https://github.com/actions/checkout
        uses: actions/checkout@v4
      - name: Download all artifacts
        uses: actions/download-artifact@v4  # Docs: https://github.com/actions/download-artifact
        with:
          path: artifacts
      # Note: We use the `-T` option of the `cp` command so that the source directory name does not
      #       get appended to the destination directory name. It's short for `--no-target-directory`.
      #       Reference: https://www.gnu.org/software/coreutils/manual/html_node/Target-directory.html
      - name: Assemble website file tree
        run: |
          mkdir -p \
            _build/html/legacy \
            _build/html/runtime \
            _build/html/workflows
          cp -R -T artifacts/legacy-home-docs-as-html _build/html/legacy
          cp -R -T artifacts/home-docs-as-html        _build/html
          cp -R -T artifacts/runtime-docs-as-html     _build/html/runtime
          cp -R -T artifacts/workflow-docs-as-html    _build/html/workflows
      - name: Inject robots.txt file into assembled website file tree
        run: |
          cp content/robots.txt _build/html/robots.txt
          ls -R _build/html
      - name: Save the result for publishing to GitHub Pages  # Docs: https://github.com/actions/upload-pages-artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _build/html

  deploy:
    name: Deploy website
    needs:
      - build
    runs-on: ubuntu-latest
    # Reference: https://github.com/actions/deploy-pages
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # Reference: https://github.com/actions/deploy-pages
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4