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: [ 61-add-link-checker ] }
  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 home, Runtime, and workflow documentation.
  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow
  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-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/runtime \
            _build/html/workflows
          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

  check-links-and-spelling:
    name: Check Links and Spelling in Documentation
    uses: ./.github/workflows/check-links-and-spelling.yml
    needs: build


  # 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