Portable absolute URLs for docstring @refs that break DiffEqDocs (#879) - #1468
Merged
ChrisRackauckas merged 1 commit intoJul 24, 2026
Conversation
Bare Documenter `@ref` targets in SciMLBase docstrings only resolve against the docs site that includes the docstring. DiffEqDocs splices these via `@docs` and then fails with `[:cross_references]` because names like `problem_type` are not documented on that site (SciML/DiffEqDocs.jl#879). Match the existing portable-link style already used for Return Codes and specialization levels: absolute `https://docs.sciml.ai/SciMLBase/stable/...` URLs for `problem_type`, `OverrideInitData`, `ReturnCode`, and `reeval_internals_due_to_modification!`. Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
This was referenced Jul 24, 2026
ChrisRackauckas
marked this pull request as ready for review
July 24, 2026 06:27
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
2 participants
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.
This PR should be ignored until reviewed by @ChrisRackauckas.
Summary
Fixes the source of DiffEqDocs.jl#879: bare Documenter
@refs inside SciMLBase docstrings only resolve against the docs site that includes them. DiffEqDocs pulls those docstrings via@docsand then fails with[:cross_references].Replace bare refs for:
problem_typeOverrideInitDataReturnCodereeval_internals_due_to_modification!with absolute
https://docs.sciml.ai/SciMLBase/stable/...URLs, matching the portable-link style already used for Return Codes and specialization levels in this package.Why not fix in DiffEqDocs
A DiffEqDocs-side workaround (extra local
@docsentries / rewrite scripts) papers over the problem. Every downstream docs site that splices these docstrings would need the same hack. Source absolute URLs work in SciMLBase docs and every re-export site.Supersedes the approach in DiffEqDocs#881.
Test plan
Developer-Extension-API)Co-Authored-By: Chris Rackauckas accounts@chrisrackauckas.com