Fix docs build: point PyCall at Conda Python so SymPy loads#228
Merged
ChrisRackauckas merged 2 commits intoJun 20, 2026
Merged
Conversation
The RK order conditions tutorial loads SymPy (via PyCall) in `@setup`/ `@example` blocks. After centralizing CI on the reusable SciML documentation workflow (SciML#219), the build environment no longer sets `PYTHON=""`, so PyCall builds against the system `/usr/bin/python3` on the GitHub runner, which has no `sympy` installed. `using SymPy` then fails with `ModuleNotFoundError: No module named 'sympy'` / `ref of NULL PyObject`, terminating the docs build (`makedocs` errors on `:setup_block`, `:example_block`). Restore the previous behavior in a workflow-independent way by setting `ENV["PYTHON"] = ""` at the top of `docs/make.jl` and rebuilding PyCall and SymPy, which makes PyCall use the private Conda.jl Python where SymPy installs `sympy` automatically. Verified locally with Julia 1.12 (the CI "1" channel): reproduced the failure by building PyCall against a Python without sympy, then ran the full `docs/make.jl` to completion (exit 0; setup/example blocks now succeed). Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The shared SciML reusable documentation workflow (adopted in SciML#219) runs `Pkg.instantiate()` without `PYTHON=""`, so PyCall builds against the runner's system `python3`. On the current `ubuntu-latest` image that interpreter has no usable `libpython`, so PyCall fails to build during the install step ("Couldn't find libpython; check your PYTHON environment variable"), before `docs/make.jl` even runs. (On older images PyCall built against system python but then `using SymPy` failed at runtime with "No module named sympy".) Make the Documentation job self-contained again and set `PYTHON: ""` on the install and build steps so PyCall uses the private Conda.jl Python into which SymPy installs `sympy`. The reusable workflow exposes no input for this, so it cannot build PyCall/SymPy-dependent docs. Verified locally with Julia 1.12 (CI "1" channel): reproduced both the libpython build failure and the missing-sympy runtime failure, then confirmed a full `docs/make.jl` build succeeds (exit 0) when PyCall is built against Conda. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The documentation build on
mainis failing (the only red check on the default branch). After CI was centralized onto the reusable SciML documentation workflow (#219), the docs build can no longer build the SymPy/PyCall-based RK order conditions tutorial:/usr/bin/python3(which has nosympy), andusing SymPyfailed at runtime withModuleNotFoundError: No module named 'sympy'/ref of NULL PyObject, terminatingmakedocson:setup_block/:example_block.ubuntu-latestimage, PyCall now fails even earlier, during the workflow'sPkg.instantiate()install step, because thatpython3(3.12) has no usable sharedlibpython:ERROR: Error building PyCall: Couldn't find libpython; check your PYTHON environment variable.Root cause
The RK order conditions tutorial loads
SymPy(via PyCall). PyCall, by default, builds against whatever system Python it finds onPATH. The repository's old (pre-#219)Documenter.ymlsetPYTHON: ""on every relevant step, forcing PyCall to use the private Conda.jl Python into which SymPy auto-installssympy. When CI was centralized onto the reusable workflow, thatPYTHON=""was dropped — and the reusabledocumentation.yml@v1exposes no input/env hook to set it — so PyCall reverted to the (now unbuildable) system Python.Fix
.github/workflows/Documenter.yml— make the Documentation job self-contained again and setPYTHON: ""on the install and build steps, so PyCall builds against the Conda Python. (This is the load-bearing CI fix; the reusable workflow cannot build PyCall/SymPy docs.)docs/make.jl— also setENV["PYTHON"] = ""and rebuild PyCall/SymPy at the top, so local docs builds work out-of-the-box regardless of the surrounding environment.Local verification (Julia 1.12, the CI "1" channel)
sympy:using SymPyfailed withModuleNotFoundError: No module named 'sympy'/ref of NULL PyObject.libpythonbuild failure in the PR CI run that used the bare reusable workflow.PYTHON=""makesPkg.build("PyCall")build against the Conda Python.docs/make.jlto completion twice: exit code 0, all stages (Doctest, ExpandTemplates, CrossReferences, CheckDocument, RenderDocument, HTMLWriter) pass; the only warning is the expected "Skipping deployment" for a local run.docs/make.jlis Runic-clean;Documenter.ymlis valid YAML.Please ignore until reviewed by @ChrisRackauckas