Skip to content

Fix Documenter binding references - #509

Merged
ChrisRackauckas merged 1 commit into
SciML:mainfrom
ChrisRackauckas-Claude:codex/fix-documenter-binding-references
Sep 7, 2026
Merged

Fix Documenter binding references#509
ChrisRackauckas merged 1 commit into
SciML:mainfrom
ChrisRackauckas-Claude:codex/fix-documenter-binding-references

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member

Summary

Render cross-references to Julia bindings with Documenter's binding-reference syntax in the component docstrings. Documenter 1.18 tightened cross-reference handling, so the prior header-style links now produce 108 strict documentation errors when reused across the API pages.

Ignore this PR until reviewed by @ChrisRackauckas.

Root cause

The affected docstrings used forms such as [Flange](@ref). That syntax asks Documenter to resolve a page-local header or anchor named Flange; these links target Julia bindings and therefore require backticked link text: [`Flange`](@ref). The source contains 65 affected links, which expand to 108 errors because several docstrings appear on more than one rendered API page.

The hosted documentation job was last green with Documenter 1.17 and became red after resolving Documenter 1.18. The stricter resolver exposed malformed existing links; this change corrects the source markup rather than constraining Documenter.

Failing before

On clean main at c873e68232f5a524a0ee727c87ad52835d1c52cf, the full documentation build on Julia 1.11 exited 1 before rendering:

$ julia +1.11 --project=docs --startup-file=no docs/make.jl
...
┌ Error: Cannot resolve @ref for md"[OnePort](@ref)" in docs/src/API/domain_reference.md.
...
ERROR: LoadError: `makedocs` encountered an error [:cross_references] -- terminating build before rendering.

$ rg -c 'Cannot resolve @ref' .validation/docs-before.log
108

The 108 failures were Flange (51), RealOutput (14), OnePort (13), HeatPort (12), RealInput (8), Support (4), and two each for VoltageSensor, Pin, and CurrentSensor.

Passing after

The identical full build with these binding links corrected exited 0 and reached rendering:

$ julia +1.11 --project=docs --startup-file=no docs/make.jl
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Automatic `version="2.29.7"` for inventory from ../Project.toml

It emitted only the pre-existing HTML-size warnings and the expected local deployment-skip warning.

Verification

$ GROUP=QA julia +release --project=. --startup-file=no -e 'using Pkg; Pkg.test()'
Test Summary: | Pass  Total     Time
QA            |   20     20  11m00.8s
Testing ModelingToolkitStandardLibrary tests passed

The first Core invocation used timeout 3600 and expired in thermal.jl after 533
passing assertions and three pre-existing broken assertions. It reported no test failure;
the complete warm-cache rerun below used a three-hour shell budget:

$ GROUP=Core timeout 10800 julia +release --project=. --startup-file=no -e 'using Pkg; Pkg.test()'
Core test files | 590 pass, 3 pre-existing broken, 593 total
Testing ModelingToolkitStandardLibrary tests passed

$ julia +release --project=../.tmp/runic-env --startup-file=no -m Runic --check --diff <eight changed files>
# exit 0

$ typos <eight changed files>
# exit 0

$ git diff --check
# exit 0

GPU and downstream test groups were not run locally. The change is limited to existing docstring link markup.

Links

🤖 Generated with Codex CLI 0.151.0 (model: gpt-5.6-sol; session: local session ID 01a0598f-11b9-72d1-91d9-b2fbb186557d).

Use binding-reference syntax for component docstring links so current
Documenter versions resolve them as Julia names instead of page anchors.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: OpenAI Codex <noreply@openai.com>
Agent-Harness: Codex CLI 0.151.0
Agent-Model: gpt-5.6-sol
Agent-Session: local session ID 01a0598f-11b9-72d1-91d9-b2fbb186557d
@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review September 7, 2026 06:13
@ChrisRackauckas
ChrisRackauckas merged commit e3bb7b5 into SciML:main Sep 7, 2026
10 of 11 checks passed
ChrisRackauckas added a commit that referenced this pull request Sep 7, 2026
- Drop stale [compat] majors older than one year (#505)
- build(deps): update DataInterpolations requirement from 6.4, 7, 8, 9.0 to 6.4, 7, 8, 9.0, 10.1 (#506)
- Support DataInterpolations v10.1 (#507)
- Fix Documenter binding references (#509)



Agent-Harness: Claude Code
Agent-Model: claude-opus-5[1m]
Claude-Session: https://claude.ai/code/session_014FEzNTLFutCmTEAZ3zBg5R

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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