build-docs.yml

name: Build Docs
on:
  push:
    branches:
      - master
  pull_request:
    types:
      - opened
      - synchronize
jobs:
  changes:
    runs-on: ubuntu-latest
    # Required permissions
    permissions:
      pull-requests: read
    # Set job outputs to values from filter step
    outputs:
      docs: ${{ steps.filter.outputs.docs }}
    steps:
    - uses: actions/checkout@v4
    # For pull requests it's not necessary to checkout the code but for master it is
    - uses: dorny/paths-filter@v3
      id: filter
      with:
        filters: |
          docs:
            - README.md
            - docs/**
            - docs_src/**
            - requirements-docs.txt
            - pyproject.toml
            - mkdocs.yml
            - mkdocs.insiders.yml
            - .github/workflows/build-docs.yml
            - .github/workflows/deploy-docs.yml
  langs:
    needs:
      - changes
    runs-on: ubuntu-latest
    outputs:
      langs: ${{ steps.show-langs.outputs.langs }}
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - uses: actions/cache@v4
        id: cache
        with:
          path: ${{ env.pythonLocation }}
          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-tests.txt') }}-v07
      - name: Install docs extras
        if: steps.cache.outputs.cache-hit != 'true'
        run: pip install -r requirements-docs.txt
      # Install MkDocs Material Insiders here just to put it in the cache for the rest of the steps
      - name: Install Material for MkDocs Insiders
        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' ) && steps.cache.outputs.cache-hit != 'true'
        run: |
          pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
          pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
          pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
      - name: Verify Docs
        run: python ./scripts/docs.py verify-docs
      - name: Export Language Codes
        id: show-langs
        run: |
          echo "langs=$(python ./scripts/docs.py langs-json)" >> $GITHUB_OUTPUT

  build-docs:
    needs:
      - changes
      - langs
    if: ${{ needs.changes.outputs.docs == 'true' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        lang: ${{ fromJson(needs.langs.outputs.langs) }}
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - uses: actions/cache@v4
        id: cache
        with:
          path: ${{ env.pythonLocation }}
          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-tests.txt') }}-v08
      - name: Install docs extras
        if: steps.cache.outputs.cache-hit != 'true'
        run: pip install -r requirements-docs.txt
      - name: Install Material for MkDocs Insiders
        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' ) && steps.cache.outputs.cache-hit != 'true'
        run: |
          pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
          pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
          pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
      - name: Update Languages
        run: python ./scripts/docs.py update-languages
      - uses: actions/cache@v4
        with:
          key: mkdocs-cards-${{ matrix.lang }}-${{ github.ref }}
          path: docs/${{ matrix.lang }}/.cache
      - name: Build Docs
        run: python ./scripts/docs.py build-lang ${{ matrix.lang }}
      - uses: actions/upload-artifact@v4
        with:
          name: docs-site-${{ matrix.lang }}
          path: ./site/**

  # https://github.com/marketplace/actions/alls-green#why
  docs-all-green:  # This job does nothing and is only used for the branch protection
    if: always()
    needs:
      - build-docs
    runs-on: ubuntu-latest
    steps:
      - name: Decide whether the needed jobs succeeded or failed
        uses: re-actors/alls-green@release/v1
        with:
          jobs: ${{ toJSON(needs) }}
          allowed-skips: build-docs