Build Documentation #54
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | |