Build Documentation #48
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_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_docs: | |
| 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.fake-tag | |
| run: | | |
| git checkout ${{ inputs.fake-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.fake-tag | |
| run: | | |
| git checkout ${{ github.sha }} | |
| - name: Create doc build dir | |
| run: | | |
| mkdir -p docs/_build/html | |
| - name: Checkout current docs | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages | |
| path: docs/_build/html | |
| - name: Build docs | |
| run: | | |
| mkdir test_cache # not really need but pytest setup relies on it | |
| # delete all files in build directory, will be replaced with new | |
| # build (don't use "make clean" as it deletes the .git folder) | |
| # need to go to nested git repository in build directory | |
| cd ./docs/_build/html | |
| git rm -r * | |
| # go back to docs folder in main repository | |
| cd ../.. | |
| make html | |
| - name: Prepare docs for publishing | |
| run: | | |
| cd docs/_build/html | |
| git add . | |
| git config user.name github-actions | |
| git config user.email [email protected] | |
| git commit -m "$GITHUB_REF_NAME ($GITHUB_JOB) ci release" | |
| - name: Publish docs | |
| if: (github.event_name == 'release') || inputs.publish | |
| run: | | |
| git push origin gh-pages --force | |
| - name: Upload docs as artifact | |
| uses: actions/upload-artifact@v4 | |
| if: github.event_name != 'release' | |
| with: | |
| name: Documentation Build | |
| path: docs/_build/html |