SciML / SciML/DataDrivenDiffEq.jl

Docs fail with Documenter 1.18 on DMDSVD cross-reference

Open Beginner friendly
#673 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Julia
Stars
430
Forks
58
Avg merge
6h 29m
Merged PRs (30d)
28

Description

Summary

The documentation build on clean master at 0c0e97f762713be03e5854e853a4c5ec7fd66411 fails after resolving Documenter 1.18.0. Documenter cannot resolve the existing DMDSVD reference in docs/src/libs/datadrivendmd/koopman.md.

Reproduction

$ TMPDIR=/home/crackauc/tmp julia +release --project=docs docs/make.jl
[ Info: CrossReferences: building cross-references.
┌ Error: Cannot resolve @ref for md"[DMDSVD](@ref)" in docs/src/libs/datadrivendmd/koopman.md.
│ - Header or `@id` anchor with slug 'DMDSVD' in docs/src/libs/datadrivendmd/koopman.md does not exist.
│ - Header or `@id` anchor with slug 'DMDSVD' is not unique in docs/src/libs/datadrivendmd/koopman.md.
└ @ Documenter ~/.julia/packages/Documenter/V8kkd/src/utilities/utilities.jl:47
ERROR: LoadError: `makedocs` encountered an error [:cross_references] -- terminating build before rendering.

The same clean checkout passes after pinning Documenter 1.17.0:

$ julia +release --project=docs -e 'using Pkg; Pkg.pin(PackageSpec(name = "Documenter", version = v"1.17.0"))'
$ TMPDIR=/home/crackauc/tmp julia +release --project=docs docs/make.jl
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Automatic `version="1.16.0"` for inventory from ../Project.toml

The latest successful master documentation run used Documenter 1.17.0: https://github.com/SciML/DataDrivenDiffEq.jl/actions/runs/33310090858

Environment

Julia Version 1.12.6
Commit 15346901f00 (2026-04-09 19:20 UTC)
Official https://julialang.org release
Linux (x86_64-linux-gnu)
CPU: AMD EPYC 7502 32-Core Processor
LLVM: libLLVM-18.1.7 (ORCJIT, znver2)

🤖 Generated with Codex CLI 0.151.0 (model: gpt-5).
Session: local Codex session ID 01a0588b-a3c5-7040-8363-097859b8f435.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Run the documented julia +release --project=docs docs/make.jl command and inspect docs/src/libs/datadrivendmd/koopman.md, focusing on the DMDSVD cross-reference. Compare the build with Documenter 1.17.0 and 1.18.0; done means the docs build completes with the newer version and resolves the reference without an error.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
build-system, documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.