Skip to content

Fix docs build: point PyCall at Conda Python so SymPy loads#228

Merged
ChrisRackauckas merged 2 commits into
SciML:mainfrom
ChrisRackauckas-Claude:fix-docs-sympy-pycall-python
Jun 20, 2026
Merged

Fix docs build: point PyCall at Conda Python so SymPy loads#228
ChrisRackauckas merged 2 commits into
SciML:mainfrom
ChrisRackauckas-Claude:fix-docs-sympy-pycall-python

Conversation

@ChrisRackauckas-Claude

@ChrisRackauckas-Claude ChrisRackauckas-Claude commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Problem

The documentation build on main is 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:

  • On the runner image at the time of the original master failure, PyCall built against the system /usr/bin/python3 (which has no sympy), and using SymPy failed at runtime with ModuleNotFoundError: No module named 'sympy' / ref of NULL PyObject, terminating makedocs on :setup_block / :example_block.
  • On the current ubuntu-latest image, PyCall now fails even earlier, during the workflow's Pkg.instantiate() install step, because that python3 (3.12) has no usable shared libpython: 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 on PATH. The repository's old (pre-#219) Documenter.yml set PYTHON: "" on every relevant step, forcing PyCall to use the private Conda.jl Python into which SymPy auto-installs sympy. When CI was centralized onto the reusable workflow, that PYTHON="" was dropped — and the reusable documentation.yml@v1 exposes no input/env hook to set it — so PyCall reverted to the (now unbuildable) system Python.

Fix

  1. .github/workflows/Documenter.yml — make the Documentation job self-contained again and set PYTHON: "" 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.)
  2. docs/make.jl — also set ENV["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)

  • Reproduced the runtime failure by pointing PyCall at a Python venv without sympy: using SymPy failed with ModuleNotFoundError: No module named 'sympy' / ref of NULL PyObject.
  • Observed the install-step libpython build failure in the PR CI run that used the bare reusable workflow.
  • Confirmed PYTHON="" makes Pkg.build("PyCall") build against the Conda Python.
  • Ran the full docs/make.jl to 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.jl is Runic-clean; Documenter.yml is valid YAML.

Please ignore until reviewed by @ChrisRackauckas

ChrisRackauckas and others added 2 commits June 19, 2026 05:50
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>
@ChrisRackauckas ChrisRackauckas marked this pull request as ready for review June 20, 2026 11:07
@ChrisRackauckas ChrisRackauckas merged commit 5089557 into SciML:main Jun 20, 2026
11 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.

2 participants