Fix Documenter binding references - #509
Merged
ChrisRackauckas merged 1 commit intoSep 7, 2026
Merged
Conversation
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
marked this pull request as ready for review
September 7, 2026 06:13
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>
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.
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.
Root cause
The affected docstrings used forms such as
[Flange](@ref). That syntax asks Documenter to resolve a page-local header or anchor namedFlange; 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
mainatc873e68232f5a524a0ee727c87ad52835d1c52cf, the full documentation build on Julia 1.11 exited 1 before rendering:The 108 failures were
Flange(51),RealOutput(14),OnePort(13),HeatPort(12),RealInput(8),Support(4), and two each forVoltageSensor,Pin, andCurrentSensor.Passing after
The identical full build with these binding links corrected exited 0 and reached rendering:
It emitted only the pre-existing HTML-size warnings and the expected local deployment-skip warning.
Verification
The first Core invocation used
timeout 3600and expired inthermal.jlafter 533passing assertions and three pre-existing broken assertions. It reported no test failure;
the complete warm-cache rerun below used a three-hour shell budget:
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).