Build and Publish Documentation workflow (PyLabRobot/pylabrobot)
The Build and Publish Documentation workflow from PyLabRobot/pylabrobot, explained and optimized by Latchkey.
CI health: C - fair
Point runs-on at Latchkey and get caching, job timeouts, SHA-pinned actions, self-healing for flaky steps, and up to 58% lower cost, applied automatically.
What it does
This is the Build and Publish Documentation workflow from the PyLabRobot/pylabrobot repository, a real project running GitHub Actions. It is shown here with attribution under its MIT license.
Below, Latchkey shows a faster, safer version produced by its optimization engine.
The workflow
name: Build and Publish Documentation
on:
push:
branches: [main]
tags: ['v*']
pull_request:
branches: [main]
permissions:
contents: read
concurrency:
group: docs-deploy
cancel-in-progress: false
jobs:
check_docs:
name: Check documentation
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python 3.11
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: pip install -e '.[dev]'
- name: Check documentation
run: |
rm -rf docs/build docs/_autosummary
make docs-check
deploy_docs:
name: Build and deploy documentation
if: github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python 3.11
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: pip install -e '.[dev]'
- name: Determine version slug
id: version
run: |
if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
echo "slug=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
else
echo "slug=dev" >> "$GITHUB_OUTPUT"
fi
- name: Build documentation
env:
DOCS_VERSION: ${{ steps.version.outputs.slug }}
run: |
rm -rf docs/build docs/_autosummary
make docs
- name: Clean build artifacts
run: rm -rf docs/build/.doctrees docs/build/.buildinfo
- name: Deploy versioned docs
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/build
destination_dir: ${{ steps.version.outputs.slug }}
publish_branch: docs
keep_files: true
cname: docs.pylabrobot.org
- name: Deploy stable
if: startsWith(github.ref, 'refs/tags/v')
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/build
destination_dir: stable
publish_branch: docs
keep_files: true
cname: docs.pylabrobot.org
The same workflow, on Latchkey
Estimated ~20% faster on cache hits, plus fewer wasted runs and a safer supply chain. Added and changed lines are highlighted.
name: Build and Publish Documentation on: push: branches: [main] tags: ['v*'] pull_request: branches: [main] permissions: contents: read concurrency: group: docs-deploy cancel-in-progress: false jobs: check_docs: timeout-minutes: 30 name: Check documentation if: github.event_name == 'pull_request' runs-on: latchkey-small steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python 3.11 uses: actions/setup-python@v5 with: cache: 'pip' python-version: '3.11' - name: Install dependencies run: pip install -e '.[dev]' - name: Check documentation run: | rm -rf docs/build docs/_autosummary make docs-check deploy_docs: timeout-minutes: 30 name: Build and deploy documentation if: github.event_name == 'push' runs-on: latchkey-small permissions: contents: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python 3.11 uses: actions/setup-python@v5 with: cache: 'pip' python-version: '3.11' - name: Install dependencies run: pip install -e '.[dev]' - name: Determine version slug id: version run: | if [[ "$GITHUB_REF" == refs/tags/v* ]]; then echo "slug=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT" else echo "slug=dev" >> "$GITHUB_OUTPUT" fi - name: Build documentation env: DOCS_VERSION: ${{ steps.version.outputs.slug }} run: | rm -rf docs/build docs/_autosummary make docs - name: Clean build artifacts run: rm -rf docs/build/.doctrees docs/build/.buildinfo - name: Deploy versioned docs uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/build destination_dir: ${{ steps.version.outputs.slug }} publish_branch: docs keep_files: true cname: docs.pylabrobot.org - name: Deploy stable if: startsWith(github.ref, 'refs/tags/v') uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/build destination_dir: stable publish_branch: docs keep_files: true cname: docs.pylabrobot.org
What changed
- Run on Latchkey managed runners with one line (
runs-on), which apply the fixes below automatically and self-heal transient failures. This example useslatchkey-small; pick the runner size that fits the job. - Cache dependency installs on the setup step so they are served from cache.
- Add a job timeout so a hung step cannot burn hours of runner time.
1 third-party action is referenced by a movable tag. Pin it to the commit SHA (Latchkey resolves and applies this automatically) so a repointed tag cannot change what runs.
What Latchkey heals here
This workflow has steps that commonly fail on transient issues (network, registries, flaky browsers). On Latchkey managed runners they are detected, retried, and self-healed instead of failing your build:
- Dependency installs
This workflow runs 2 jobs per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.