compile-legacy-workflow-documentation.yml

# This GitHub Actions workflow compiles the Sphinx documentation into web-based documentation.
# Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
name: Compile legacy workflow documentation into HTML

on:
  push: { branches: [ main ] }
  workflow_dispatch: { }
  # Allow this workflow to be called by other workflows.
  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows
  workflow_call: { }

jobs:
  compile:
    name: Compile
    runs-on: ubuntu-latest
    defaults:
      run:
        # Set a default working directory for all `run` steps in this job.
        # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun
        working-directory: legacy/workflow-documentation
    permissions:
      contents: read
    steps:
      - name: Check out commit  # Docs: https://github.com/actions/checkout
        uses: actions/checkout@v4
      - name: Set up Python  # Docs: https://github.com/actions/setup-python
        uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - name: Install Sphinx  # Docs: https://pypi.org/project/Sphinx/
        run: pip install Sphinx
      - name: Install other dependencies
        run: pip install -r requirements.txt
      - name: Compile source documents into HTML
        run: sphinx-build -b html src ${{ github.workspace }}/legacy/workflow-documentation/_build/html
        # Upload the result as an "artifact" so it can then be downloaded and used by another job.
      - name: Save the HTML for publishing later  # Docs: https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@v4
        with:
          name: legacy-workflow-documentation-as-html
          # Note: Relative `path` values here are relative to the _workspace_, not to the current working directory.
          #       Reference: https://github.com/actions/upload-artifact/pull/477#issue-2044900649
          path: legacy/workflow-documentation/_build/html
          if-no-files-found: error
          retention-days: 1  # Note: 1 day is the shortest period possible