docs.yml

name: Build Documentation


on:
  workflow_call:
    inputs:
      publish:
        required: true
        type: boolean
      test-build:
        required: true
        type: boolean
  workflow_dispatch:
    inputs:
      publish:
        description: "Publish documentation"
        required: true
        type: boolean
      install-ref:
        # install-ref 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
        description: "Install at this ref instead of the current commit"
        required: false
        type: string
      build-ref:
        # build-ref can be used to specify a custom ref at which should be checked
        # out before building the documentation. Else, the ref associated with
        # the workflow run is used
        description: "Checkout this ref after installation before building the documentation"
        required: false
        type: string
      test-build:
        # does not use the versioning setup and only does a simple html build
        # enables running on push to main when no access to secrets is available
        description: "Unversioned test build"
        required: false
        type: boolean
        default: false
  release:
    types: [ released ]
  push:
    branches:
      - main
    paths:
      - 'src/docs/**'
      - 'src/fastf1/**'
      - 'src/examples/**'
      - 'src/requirements/**'
      - 'src/pyproject.toml'
      - 'src/.github/workflows/docs.yml'


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 -r requirements/doc-build.txt

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

      - name: Restore cache for FastF1
        id: cache-doc-restore
        uses: actions/cache/restore@v4
        with:
          path: ./doc_cache
           # Restore any matching cache independent of hash suffix. We cannot
           # know if anything has changed at this stage.
          key: fastf1-doc-cache-${{ hashFiles('./doc_cache/**/*.*') }}
          restore-keys: |
            fastf1-doc-cache

      - name: Install at install ref
        if: inputs.install-ref != ''
        run: |
          git checkout ${{ inputs.install-ref }}

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

      - name: Re-checkout current commit after install at install ref or checkout build-ref if specified
        run: |
          if [ "${{ inputs.build-ref }}" != "" ]; then
            git checkout ${{ inputs.build-ref }}
          else
            git checkout ${{ github.sha }}
          fi

      - name: Initialize Documentation build directory
        run: |
          mkdir -p docs/_build/html

      - name: Checkout currently deployed build output from external repo to build directory
        uses: actions/checkout@v5
        # skip for pull requests (no access to secret + unversioned build is sufficient)
        if: (!inputs.test-build) && ((github.event_name == 'release') || (github.ref == 'refs/heads/main') || (github.event_name == 'workflow_dispatch'))
        with:
          repository: theOehrly/fastf1-doc-build-output
          path: docs/_build/html
          token: ${{ secrets.GH_PAT_DOC_BUILD_REPO }}

      - name: Build docs
        run: |
          mkdir test_cache  # not really need but pytest setup relies on it 
          cd docs
          chmod +x ./setup_versioning.sh
          if [[ "${{ inputs.test-build }}" == "true" ]]; then
            make html  # simple unversioned test build
          elif [[ "${{ github.event_name }}" == "release" ]]; then
            make version-build VERSION="${{ github.ref_name }}"  #  versioned build: release
          elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            make version-build  # versioned build: dev
          elif [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            make version-build  # versioned build: dev
          else
            make html  # unversioned build
          fi

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

      - name: Save cache for FastF1
        id: cache-doc-save
        # Save the cache even in case of a failure but only if the content of
        # the cached directory has changed.
        if: always() && steps.cache-doc-restore.outputs.cache-matched-key != hashFiles('./doc_cache/**/*.*')
        uses: actions/cache/save@v4
        with:
          key: fastf1-doc-cache-${{ hashFiles('./doc_cache/**/*.*') }}
          path: ./doc_cache

      - name: Push build changes to external repo
        # If this was either a release, run manually with publish=true or a push to main
        if: (!inputs.test-build) && ((github.event_name == 'release') || (github.ref == 'refs/heads/main') || inputs.publish)
        uses: EndBug/add-and-commit@v9
        with:
          cwd: "docs/_build/html"
          add: "."
          author_name: "github-actions-${{ github.ref_name }}"
          default_author: "github_actions"
          message: "Update documentation: triggered by ${{ github.event_name }}${{ inputs.publish && ' (publish=true)' || '' }}${{ inputs.install-ref != '' && ', install-ref=' && inputs.install-ref || '' }}${{ inputs.build-ref != '' && ', build-ref=' && inputs.build-ref || '' }} see workflow run: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          push: true

  deploy:
    # deploy releases, dev builds on main and manual runs with publish=true
    if: (!inputs.test-build) && ((github.event_name == 'release') || (github.ref == 'refs/heads/main') || 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