name: Documentation
on:
push:
tags:
- "v*"
pull_request:
paths:
- "docs/**"
- "hooks/**"
- "mkdocs.yml"
- "pyproject.toml"
- ".github/workflows/docs.yml"
workflow_dispatch:
permissions:
contents: write
concurrency:
group: "docs-gh-pages"
cancel-in-progress: false
jobs:
build:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.x"
cache: pip
cache-dependency-path: docs/requirements.txt
- name: Install documentation dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -r docs/requirements.txt
- name: Build documentation
run: python -m mkdocs build --strict
deploy:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.x"
cache: pip
cache-dependency-path: docs/requirements.txt
- name: Install documentation dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -r docs/requirements.txt
- name: Configure Git
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
- name: Resolve documentation version
shell: bash
run: |
if [[ "${GITHUB_REF_TYPE}" == "tag" && "${GITHUB_REF_NAME}" == v* ]]; then
VERSION="${GITHUB_REF_NAME#v}"
else
VERSION="$(python -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"])')"
fi
echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
echo "Deploying documentation version ${VERSION}"
- name: Deploy versioned documentation
run: |
mike deploy --push --update-aliases "${VERSION}" latest
mike set-default --push latest