Skip to content

Build Documentation #48

Build Documentation

Build Documentation #48

Workflow file for this run

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