Skip to content

Fix the Documentation build: load the packages the copied API pages need - #900

Merged
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:fix-docs-build
Aug 28, 2026
Merged

Fix the Documentation build: load the packages the copied API pages need#900
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:fix-docs-build

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member

Summary

The Documentation workflow has been failing on master with

ERROR: LoadError: `makedocs` encountered errors [:cross_references, :linkcheck] -- terminating build before rendering.

docs/make.jl copies OrdinaryDiffEq's and StochasticDiffEq's own docs/src trees into docs/src/api/, so this build has to supply the same load-time scope those pages were written against. Several packages were missing from it:

  • OrdinaryDiffEqTaylorSeries — the copied explicit/TaylorSeries.md documents OrdinaryDiffEqTaylorSeries.ExplicitTaylor/ExplicitTaylor2/ExplicitTaylorAdaptiveOrder, which produced the UndefVarError: OrdinaryDiffEqTaylorSeries not defined in Main in the log and left that page's API section empty.
  • GlobalDiffEq — the copied globalerrorcontrol/GlobalDiffEq.md documents GlobalRichardson; without the package the @docs block reported an undefined binding and the page's [GlobalRichardson](@ref) became a hard :cross_references error.
  • ADTypes and SciMLOperators — the released OrdinaryDiffEq api/common_interface.md now uses @autodocs blocks whose Modules = [...] are evaluated in this scope. These are already docs/Project.toml dependencies but were never loaded in make.jl, so the AD and operator sections failed to expand.

Both GlobalDiffEq and OrdinaryDiffEqTaylorSeries are added to docs/Project.toml, matching how OrdinaryDiffEq's own docs/make.jl loads them.

Two classes of failure are owned upstream and can't be resolved from here:

  • The remaining unresolvable @refs (AutoSwitch, AutoAlgSwitch, StochasticCompositeCache, has_global_error) come from docstrings in StochasticDiffEqCore and SciMLBase that link to solver internals this aggregated site does not pull in as @docs — documenting them here would cascade into their own internal @refs (unwrap_alg, get_current_alg_order, cache types). :cross_references therefore joins :docs_block and :missing_docs in warnonly, which are already tolerated for exactly this reason.
  • Three absolute URLs baked into the copied pages and docstrings are unreachable and are added to linkcheck_ignore: SciMLBase/stable/interfaces/Problem_Traits/ (in SciMLBase's pages.jl but not on the deployed site), OrdinaryDiffEq/stable/devtools/internals/public_api/ (this build deliberately drops the devtools tree), and a paywalled SIAM DOI cited by the ADTypes docstrings that the AD section now renders.

No sections are disabled and no package versions are bumped.

Test plan

  • Full local build on this branch: julia --project=docs docs/make.jl completes with exit code 0 and renders the whole site (35 MB in docs/build). No Error: lines remain; only pre-existing warnings (missing_docs, docs_block, size-threshold notices).
  • Verified in the rendered HTML that the previously broken sections now have content: ExplicitTaylor2 on api/ordinarydiffeq/explicit/TaylorSeries/, GlobalRichardson on api/ordinarydiffeq/globalerrorcontrol/GlobalDiffEq/, and the AutoForwardDiff/AbstractColoringAlgorithm autodocs output on api/ordinarydiffeq/api/common_interface/.
  • linkcheck passes with no 4xx/5xx errors.
  • Confirm the Documentation workflow is green on CI.

Made with Cursor

…refs failing the build

The Documentation build aggregates OrdinaryDiffEq's and StochasticDiffEq's own
docs/src trees, so it has to provide the same load-time scope those pages were
written against. It was missing OrdinaryDiffEqTaylorSeries and GlobalDiffEq
(leaving the ExplicitTaylor and GlobalRichardson sections empty and their
`@ref`s unresolvable), and ADTypes and SciMLOperators, which the `@autodocs`
blocks in the copied api/common_interface.md evaluate in this scope.

The remaining cross-references come from upstream docstrings that point at
solver internals this site does not document, and cannot be resolved from here,
so :cross_references joins :docs_block and :missing_docs in warnonly. Three
absolute URLs baked into the copied pages and docstrings are unreachable
(two docs.sciml.ai pages that are not deployed, one paywalled DOI) and are
added to linkcheck_ignore.

Co-authored-by: Cursor <cursoragent@cursor.com>
@ChrisRackauckas
ChrisRackauckas merged commit 4dc2bca into SciML:master Aug 28, 2026
3 of 4 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