From 2bcbef3e68c18c706a3820155d4ec29ae67b33c5 Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Wed, 2 Sep 2026 14:38:22 +0200 Subject: [PATCH] docs: fix unresolvable @extref in _strategy_parameter docstring (#943) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.md | 2 ++ docs/make.jl | 15 +++++++++------ src/helpers/print.jl | 9 ++++----- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b986fbd72..8259b4eb6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,8 @@ Dependency realignment onto the released control-toolbox ecosystem, the v2.0 → - The documentation site was rewritten onto a new sitemap (getting started, modelling, solve, results, flows, geometry, an examples gallery, and a thematic API reference) and a v2.0 → v2.1 migration page added. The retired v2.0 manuals are kept under `docs/attic/` +- **`_strategy_parameter` docstring no longer emits an unresolvable `@extref`** ([#943](https://github.com/control-toolbox/OptimalControl.jl/issues/943)). It cross-referenced `CTBase.Strategies.parameter` by method signature (`parameter(T, default)` / `parameter(T)`), but CTBase's auto-generated reference indexes the function under a single anchor, so neither link resolved. Collapsed to the one anchor; `docs/make.jl`'s `warnonly` comment refreshed. The remaining `@extref` warnings (`Plots.plot(::CTModels.Solutions.Solution)`) are fixed upstream in [CTModels 0.19.4-beta](https://github.com/control-toolbox/CTModels.jl/issues/427). + ### 📦 Dependencies - **Realigned on the released ecosystem** — every sibling resolves from the General registry with no `Pkg.develop`: CTBase `0.28`→`0.29`, CTModels `0.15`→`0.18`, CTSolvers `0.4`→`0.5`, CTFlows `0.16`→`0.17`, CTParser `0.8`→`0.9`, CTLie `0.1`→`0.2`; CTDirect stays pinned to `1` (the major alone, per the pinning-granularity rule) diff --git a/docs/make.jl b/docs/make.jl index cae622d2a..ec31cc372 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -263,12 +263,15 @@ with_api_reference(src_dir, ext_dir) do api_pages return makedocs(; draft=draft, remotes=nothing, # Disable remote links. Needed for DocumenterReference - # Not fully zero: 2 unresolved @ref (DOCPCache, category :cross_references) and 6 - # unresolved @extref (CTModels.Solution / CTBase.Strategies.parameter — a *separate* - # category, :external_cross_references, registered by DocumenterInterLinks, not - # Documenter itself) are upstream defects, tracked at control-toolbox/CTDirect.jl#630, - # control-toolbox/CTModels.jl#416 and control-toolbox/CTBase.jl#543 respectively. Drop - # this exclusion once those land — see .reports/campaign/D-api-reference.md. + # Not fully zero: 2 unresolved @ref remain (DOCPCache, category :cross_references), + # tracked at control-toolbox/CTDirect.jl#630 — drop :cross_references once that lands. + # The @extref backlog (category :external_cross_references, registered by + # DocumenterInterLinks, not Documenter itself) is cleared: the CTBase.Strategies.parameter + # links were this repo's own signature-suffixed docstring (#943, fixed here) and the + # Plots.plot(::CTModels.Solutions.Solution) links were CTModels' extension docstrings + # (control-toolbox/CTModels.jl#427, fixed in CTModels 0.19.4-beta). Once that release is + # in docs/Manifest.toml, :external_cross_references can be dropped from this list so a + # future unresolved @extref fails the build. See .reports/campaign/D-api-reference.md. # # :example_block is deliberately *not* here: the one remaining un-expanded @example # (CTParser's @def docstring, control-toolbox/CTParser.jl#341, transcluded onto diff --git a/src/helpers/print.jl b/src/helpers/print.jl index fd984fd61..d19c21b1a 100644 --- a/src/helpers/print.jl +++ b/src/helpers/print.jl @@ -331,11 +331,10 @@ $(TYPEDSIGNATURES) Parameter type of a strategy, or `nothing` when it declares none. -Since CTBase 0.28.8-beta this is a thin wrapper around -[`CTBase.Strategies.parameter(T, default)`](@extref) — the non-throwing counterpart to -[`CTBase.Strategies.parameter(T)`](@extref) requested as -[CTBase#518](https://github.com/control-toolbox/CTBase.jl/issues/518), so display no longer -needs its own `try`/`catch` around `NotImplemented`. +Since CTBase 0.28.8-beta this is a thin wrapper around the two-argument form of +[`CTBase.Strategies.parameter`](@extref) — the non-throwing counterpart to its one-argument +form ([CTBase#518](https://github.com/control-toolbox/CTBase.jl/issues/518)), so display no +longer needs its own `try`/`catch` around `NotImplemented`. Display must not be the thing that crashes on a third-party strategy which simply chose not to be parameterized. Every in-tree strategy implements the contract, so the fallback path below is