docs: fix unresolvable @extref in _strategy_parameter docstring (#943) - #944
Merged
Conversation
The `_strategy_parameter` docstring cross-referenced CTBase's `parameter` function by method signature — `parameter(T, default)` and `parameter(T)` — but CTBase's auto-generated reference indexes `Strategies.parameter` under a single function anchor, with no per-method signature. Neither link resolved. Same anti-pattern CTBase removed from its own docstrings in CTBase#543. Collapsed both to the single `[`CTBase.Strategies.parameter`](@extref)` anchor, keeping the prose that distinguishes the one- and two-argument forms. Refreshed the `docs/make.jl` warnonly comment: CTBase#543 and CTModels#416 are closed; the residual @extref were (a) this docstring, fixed here, and (b) CTModels' extension docstrings (CTModels#427, fixed in CTModels 0.19.4-beta). Verified: docs build ExtCrossReferences step reports 0 unresolved @extref (was 6). Documentation-only; no API or behaviour change; no version bump. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
ocots
added
documentation
ocots
added a commit
that referenced
this pull request
Sep 2, 2026
Both cross-reference backlogs are cleared: - @extref: `_strategy_parameter` (#944) + CTModels' extension docstrings (CTModels.jl#428, shipped in CTModels 0.19.4-beta) - @ref/DOCPCache: CTDirect#630 (closed) So `makedocs` no longer needs `warnonly` — an unresolved `@ref`/`@extref`, or a broken `@example`/`@repl`, now fails the build. Verified with the sibling inventories forced to resolve remotely (as on CI): full build, exit 0, zero unresolved references. Also: - docs env moves to CTBase 0.30.4-beta + CTModels 0.19.4-beta; docs/src/assets/Manifest.toml regenerated. - Project.toml 2.2.0-beta -> 2.2.1-beta (docs-infra patch, no API/runtime change); CHANGELOG + BREAKING get a 2.2.1-beta section collecting this plus the already-merged #944 (extref), #949 (draft=false default) and #951 (CI-only remote inventories). Co-Authored-By: Claude Sonnet 5 <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
1 participant
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.
Closes #943.
Problem
The
_strategy_parameterdocstring (src/helpers/print.jl) cross-referenced CTBase'sparameterfunction by method signature:Neither link resolves. CTBase's auto-generated API reference documents
Strategies.parameteras a single
jl:function— one inventory anchor,CTBase.Strategies.parameter, noper-method signature. A signature-suffixed
@extrefonly resolves when the target docssplit the docstring per method with a
@docsblock, which CTBase does not do (its #543 fixjust rewrote CTBase's own prose to drop the suffix — it did not add per-method anchors).
These 2 links were 2 of the 6
@extreferrors in thewarnonly=[:cross_references, :external_cross_references]backlog, on the generatedapi/internals.md. Thedocs/make.jlcomment attributed them to CTBase#543, now closed.Fix
src/helpers/print.jl— collapse both links to the single function anchor[CTBase.Strategies.parameter](@extref), keeping the prose that distinguishes theone- and two-argument forms.
docs/make.jl— refresh thewarnonlycomment. CTBase#543 and CTModels#416 are closed;the residual
@extrefwere this docstring (fixed here) and CTModels' extensiondocstrings (Extension plotting docstrings
@extrefPlots.plot(::CTModels.Solutions.Solution), an anchor that cannot exist CTModels.jl#427 → CompatHelper: bump compat for CTDirect to 0.14, (drop existing compat) #428, fixed in CTModels 0.19.4-beta).CHANGELOG.md— unreleased📚 Documentationnote. No version bump, no BREAKING entry.Verification
Local docs build (
julia --project=. docs/make.jl), against CTModels#428:ExtCrossReferencesreports 0 unresolved@extref(was 6).CrossReferences,CheckDocument,RenderDocumentall pass; build exits 0.The other 4
@extref(Plots.plot(::CTModels.Solutions.Solution)) are owned bycontrol-toolbox/CTModels.jl#428; this PR clears its own 2 regardless of that landing.
Once CTModels 0.19.4-beta is in
docs/Manifest.toml,:external_cross_referencescan bedropped from
warnonly(separate follow-up) so a future unresolved@extreffails thebuild.
Documentation-only; no API or behaviour change.
🤖 Generated with Claude Code