Skip to content

docs: repair strict cross-references - #4980

Merged
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:agent/fix-strict-doc-crossrefs
Aug 18, 2026
Merged

docs: repair strict cross-references#4980
ChrisRackauckas merged 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:agent/fix-strict-doc-crossrefs

Conversation

@ChrisRackauckas-Claude

@ChrisRackauckas-Claude ChrisRackauckas-Claude commented Aug 15, 2026

Copy link
Copy Markdown
Member

Ignore this PR until it has been reviewed by @ChrisRackauckas.

What changed

Strict Documenter exposed 34 unresolved cross-references on current master.

This PR keeps local ModelingToolkit references as qualified Documenter references, links dependency-owned APIs to their canonical SciML documentation, and renders internal-only helper names as code instead of pretending they are public documentation targets. It does not change behavior or public API.

Failure before

On the unmodified f3248317cb51e08e78fb3d1729286905ad61d6d4 base:

DISPLAY=:0 JULIA_DEBUG=Documenter xvfb-run -a -s '-screen 0 1024x768x24' \
  julia +lts --startup-file=no --project=docs/ --code-coverage=user docs/make.jl

The command exited 1, and:

$ rg -c 'Cannot resolve @ref' docs-before.log
34
ERROR: LoadError: `makedocs` encountered errors [:docs_block, :missing_docs, :cross_references] -- terminating build before rendering.

The same failure is visible in the clean-master docs job:
https://github.com/SciML/ModelingToolkit.jl/actions/runs/31869817836/job/94981845495

A formal bisect of the strict cross-reference gate identified 92c27bb9fdcaa024ff190feb3d665452e33f9bd8 (Adopt SciMLTesting 2.4 strict QA) as the first bad commit.

Verification after

On this branch, based directly on f3248317cb51e08e78fb3d1729286905ad61d6d4:

DISPLAY=:0 JULIA_DEBUG=Documenter xvfb-run -a -s '-screen 0 1024x768x24' \
  julia +lts --startup-file=no --project=docs/ --code-coverage=user docs/make.jl

The command still exits 1 for the independently tracked duplicate-doc and missing-doc failures, but the cross-reference discriminator is clean:

$ rg 'Cannot resolve @ref' docs-after-crossrefs.log | wc -l
0
ERROR: LoadError: `makedocs` encountered errors [:docs_block, :missing_docs] -- terminating build before rendering.

Both new canonical external links returned HTTP 200 during Documenter link checking.

Mechanical checks:

git diff --name-only --diff-filter=ACM | rg '\.jl$' |
  xargs julia +lts --startup-file=no -e 'using Runic; exit(Runic.main(ARGS))' -- --check
git diff --check
git diff --name-only --diff-filter=ACM -z | xargs -0 typos

All three exited 0.

QA:

GROUP=QA julia +lts --startup-file=no --project -e 'using Pkg; Pkg.test()'

The command reproduced the current-master ExplicitImports failure without a branch-specific regression:

Some tests did not pass: 38 passed, 0 failed, 4 errored, 0 broken.
ExplicitImports | 4 errors

GPU, downstream, Julia pre, and non-QA test groups were not run because this is a documentation-only change.

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

Pushed 4be377a98a354ce4f7fef9953a413e3100b8d10b to fix the Runic indentation failure at docs/make.jl:50 (], aligned to four spaces).

Verification on the pushed tree:

  • /home/crackauc/.juliaup/bin/julia +1.12.4 --project=@runic --startup-file=no -m Runic --check --diff docs/make.jl passed.
  • typos docs/make.jl passed.
  • git diff --check passed.
  • Full docs build passed at the preceding docs commit (0302915bd9); this push changes only whitespace in docs/make.jl.

@ChrisRackauckas-Claude
ChrisRackauckas-Claude force-pushed the agent/fix-strict-doc-crossrefs branch 2 times, most recently from b325901 to 17b1a65 Compare August 17, 2026 09:31
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

Rebased the docs-only strict cross-reference fix onto current master at 17b1a65960a6fe889379ce5fcfd6deb47f50ee48 and pushed it to this draft PR.

Local verification: root ModelingToolkit QA 52/52, Runic passed, git diff --check passed. Typos reports only the pre-existing unrelated inferrable in untouched test/analysis_points.jl. The full docs build is still running locally; I will report its exit result separately. Please ignore until reviewed by @ChrisRackauckas.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude
ChrisRackauckas-Claude force-pushed the agent/fix-strict-doc-crossrefs branch from 17b1a65 to b6b9f8d Compare August 17, 2026 18:37
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

Rebased this PR onto current master 29f589e. Runic, added-line typos, and git diff --check passed. The docs environment was instantiated successfully and the full docs build completed doctests, template expansion, cross-reference construction, and document checks before stopping only on GitHub NEWS.md HTTP 429 during external link checking; Claytex and codecov redirects were warnings. The focused InterfaceI test was run locally after the rebase; its final result will be recorded once the active process completes.

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

The focused InterfaceI verification has completed on the rebased head: Test Summary reports 1,487 passed, 3 broken, 1,490 total in 49m11.4s, followed by Testing ModelingToolkit tests passed. The three broken cases are existing expected broken tests; no branch-specific test failure was reported.

@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review August 18, 2026 02:58
@ChrisRackauckas
ChrisRackauckas merged commit 8b337a8 into SciML:master Aug 18, 2026
74 of 93 checks passed
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