Skip to content

fix(ci): pin docs-deploy to Python 3.12 - #106

Merged
celefthe merged 1 commit into
mainfrom
hotfix-docs-deployment-3
Aug 6, 2026
Merged

fix(ci): pin docs-deploy to Python 3.12#106
celefthe merged 1 commit into
mainfrom
hotfix-docs-deployment-3

Conversation

@celefthe

@celefthe celefthe commented Aug 6, 2026

Copy link
Copy Markdown
Member

Follow-up to #105

After merging #105, the workflow failed again on the same push — a third, previously-masked layer of the same underlying issue (see run 31113516131):

× Failed to build `av==15.0.0`
╰─▶ pkg-config could not find libraries ['avformat', 'avcodec', ...]
hint: `av` (v15.0.0) was included because `mesoscopy` depends on `av`

--group docs (from #105) correctly installs the mesoscopy project itself, but that also pulls in the project's own runtime dependencies (av, napari, pyqt5, etc., from pyproject.toml's [project.dependencies]). uv python install with no version argument installs the latest Python (3.14 on the runner), and av==15.0.0 has no prebuilt wheel for cp314 (only up to cp313), so uv tries to build it from source — which fails because the runner has no ffmpeg dev headers.

This is the same wheel-availability problem as the original lxml issue, just one layer deeper. The Build & Test workflow already proves this exact dependency set installs cleanly on Python 3.12/3.13 (it runs a ["3.12", "3.13"] matrix on every push).

Fix

       - name: Set up Python
-        run: uv python install
+        run: uv python install 3.12

       - name: Deploy docs
-        run: uv run --no-default-groups --group docs mkdocs gh-deploy --force --clean --verbose
+        run: uv run --python 3.12 --no-default-groups --group docs mkdocs gh-deploy --force --clean --verbose

Verification

uv run --python 3.12 --no-default-groups --group docs mkdocs build --verbose exits 0 locally — installs cleanly (prebuilt wheels for av etc. on 3.12), mesoscopy imports, all pages including the CLI reference build.

🤖 Generated with Claude Code

#105 fixed the missing-project-import issue by using --group docs
instead of --only-group docs, but that also installs mesoscopy's own
runtime dependencies (av, napari, pyqt5, etc., per pyproject.toml
[project.dependencies]). uv python install with no version picks the
latest Python (3.14 on the runner), and av==15.0.0 has no prebuilt
wheel for cp314 -- only up to cp313 -- so uv falls back to building
from source, which fails because the runner has no ffmpeg dev headers:

    Package libavformat was not found in the pkg-config search path.

The Build & Test workflow already proves 3.12/3.13 install this same
dependency set cleanly (it runs the matrix against both). Pin the
docs-deploy job to 3.12 to match.

Verified locally: `uv run --python 3.12 --no-default-groups --group
docs mkdocs build --verbose` exits 0.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@celefthe
celefthe merged commit b32a5d2 into main Aug 6, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant