docs.yml

name: Build Documentation


on:
  workflow_call:
    inputs:
      publish:
        required: true
        type: boolean
  workflow_dispatch:
    inputs:
      publish:
        required: true
        type: boolean
      pin-tag:
        # pin-tag can be used to keep the latest X.Y.Z release tag instead of
        # a X.Y.Z-devN tag when updating the docs after a release
        required: false
        type: string
  release:
    types: [ released ]


env:
  # Set environment variable with value from configuration variable
  FASTF1_DOCS_ERGAST_BACKEND_OVERRIDE: ${{ vars.FASTF1_DOCS_ERGAST_BACKEND_OVERRIDE }}


jobs:
  build:
    if: (!contains(github.event.head_commit.message, '[skip-doc-build]')) || inputs.publish
    name: Build Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Setup python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # fetch the complete repo history (for setuptools-scm)

      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-cache-${{ hashFiles('requirements/*.txt') }}
          restore-keys: |
            pip-cache

      - name: Install python requirements
        run: |
          python -m pip install --upgrade pip
          python -m pip install --upgrade build twine
          python -m pip install -r requirements/dev.txt

      - name: Create cache directory
        run: |
          mkdir doc_cache  # make sure cache dir exists

      - name: Cache FastF1
        uses: actions/cache@v4
        with:
          save-always: true
          path: ./doc_cache
          key: fastf1-doc-cache-${{ hashFiles('*.*') }}
          restore-keys: |
            fastf1-doc-cache

      - name: Install at pinned tag
        if: inputs.pin-tag != ''
        run: |
          git checkout ${{ inputs.pin-tag }}

      - name: Install Fast-F1 from sources
        run: |
          python -m pip install -e .

      - name: Re-checkout current commit after install at pinned tag
        if: inputs.pin-tag != ''
        run: |
          git checkout ${{ github.sha }}

      - name: Build docs
        run: |
          mkdir test_cache  # not really need but pytest setup relies on it 
          cd docs
          make html

      - name: Upload docs as artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/_build/html/


  deploy:
    if: (github.event_name == 'release') || inputs.publish
    name: Deploy Documentation

    # Add a dependency to the build job
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    # Specify runner + deployment step
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action