Skip to content

docs: repair strict cross-references - #4980

Draft
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:agent/fix-strict-doc-crossrefs
Draft

docs: repair strict cross-references#4980
ChrisRackauckas-Claude wants to merge 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 from 4be377a to b325901 Compare August 16, 2026 22:44
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude
ChrisRackauckas-Claude force-pushed the agent/fix-strict-doc-crossrefs branch 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.

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