Skip to content

Fix master docs build: resolve upstream @ref cross-references (#879) - #881

Closed
ChrisRackauckas-Claude wants to merge 2 commits into
SciML:masterfrom
ChrisRackauckas-Claude:agent/fix-879-cross-ref-docs
Closed

Fix master docs build: resolve upstream @ref cross-references (#879)#881
ChrisRackauckas-Claude wants to merge 2 commits into
SciML:masterfrom
ChrisRackauckas-Claude:agent/fix-879-cross-ref-docs

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member

This PR should be ignored until reviewed by @ChrisRackauckas.

Fixes #879.

Problem

Master Documentation fails with makedocs encountered an error [:cross_references]. Bare @refs live inside upstream SciMLBase / OrdinaryDiffEq docstrings spliced via @docs without local targets.

Broken refs (from run 29313032312):

  • problem_type, OverrideInitData, ReturnCode, reeval_internals_due_to_modification! (SciMLBase)
  • Developer-Extension-API ×3 (OrdinaryDiffEq API pages; target lives under devtools/, which DiffEqDocs deletes)

Fix

  1. Add @docs entries for the four SciMLBase names in the appropriate local pages.
  2. Before deleting devtools/, rewrite copied [...](@ref Developer-Extension-API) links to the published OrdinaryDiffEq public_api URL.

Does not add :cross_references to warnonly.

Fixes SciML#879.

Documenter failed on master with [:cross_references] because bare `@ref`
links inside upstream SciMLBase/OrdinaryDiffEq docstrings are spliced into
this site via `@docs` without local targets:

- Add `@docs` for SciMLBase.problem_type, OverrideInitData, ReturnCode, and
  reeval_internals_due_to_modification! so those bare refs resolve.
- Rewrite copied OrdinaryDiffEq `[...](@ref Developer-Extension-API)` links
  to the published OrdinaryDiffEq public_api page before deleting
  `devtools/` (those pages cannot build inside DiffEqDocs).

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude
ChrisRackauckas-Claude force-pushed the agent/fix-879-cross-ref-docs branch from 4b7f442 to b14b2d1 Compare July 23, 2026 20:39
@ChrisRackauckas-Claude
ChrisRackauckas-Claude marked this pull request as ready for review July 23, 2026 20:39
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

CI note (agent): Documentation workflow has if: github.event_name == 'push' || !github.event.pull_request.draft, so the docs build was skipped while draft. Marked ready for review so Documentation can run and validate the #879 cross-ref fix.

Also rebased onto current master (includes #880 FAQ).

This PR should still be ignored until reviewed by @ChrisRackauckas.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas

Copy link
Copy Markdown
Member

No fix the actual bad ref

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

Closing in favor of source fixes rather than DiffEqDocs-side @docs padding / make.jl rewrites.

Bare @ref targets in upstream docstrings only resolve against the docs site that includes them. DiffEqDocs should not paper over that with local targets.

Upstream PRs:

Once those land (and are registered / resolved by DiffEqDocs CI), master docs should go green without this PR.

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.

Documentation build failing on master: bare @ref in upstream docstrings + floating doc dependency versions

2 participants