From 4c68ac14a2a8efa9870e8cd6b257f75fe29daddc Mon Sep 17 00:00:00 2001
From: Olivier Cots <olivier.cots@irit.fr>
Date: Wed, 2 Sep 2026 14:37:44 +0200
Subject: [PATCH] docs: drop unresolvable @extref in plotting-extension
 docstrings (#427)

The `plot!` / `Makie.plot` / `Makie.plot!` docstrings cross-referenced the
public method as `[`Plots.plot(::CTModels.Solutions.Solution)`](@extref)`, an
anchor that cannot exist: the public `Plots.plot` / `Makie.plot` methods on a
`Solution` are defined in weak-dependency extensions, so the inventory registers
only the internal `CTModelsPlots._plot` / `CTModelsMakie._plot` helpers. The
links are now plain prose.

Also clears four `@extref` warnings from OptimalControl.jl's docs build, where
these docstrings are transcluded onto results/plot.md, results/plot-makie.md and
the generated api/io.md. Follow-on to #416.

Documentation-only; no runtime or public-API change. Bumps to 0.19.4-beta.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 BREAKING.md          | 12 ++++++++++++
 CHANGELOG.md         | 20 ++++++++++++++++++++
 Project.toml         |  2 +-
 ext/CTModelsMakie.jl |  6 +++---
 ext/CTModelsPlots.jl |  3 +--
 5 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/BREAKING.md b/BREAKING.md
index d84252b5..3e87343a 100644
--- a/BREAKING.md
+++ b/BREAKING.md
@@ -4,6 +4,18 @@
 
 This document describes breaking changes in CTModels releases and how to migrate your code.
 
+## [0.19.4-beta] - unreleased
+
+### No Breaking Changes
+
+This release is documentation-only. The `plot!` / `Makie.plot` / `Makie.plot!` docstrings
+in the plotting extensions no longer cross-reference the public method with an `@extref`
+anchor that cannot resolve — the public `Plots.plot` / `Makie.plot` methods on a `Solution`
+live in weak-dependency extensions, so only the internal `_plot` helpers are in the
+inventory ([#427](https://github.com/control-toolbox/CTModels.jl/issues/427), follow-on to
+[#416](https://github.com/control-toolbox/CTModels.jl/issues/416)). The links are now plain
+prose. No runtime behavior or public API changed; no migration required.
+
 ## [0.19.3-beta] - unreleased
 
 ### No Breaking Changes
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 028c67d7..cdcce60f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.4-beta] - unreleased
+
+### 📚 Documentation
+
+- **Drop unresolvable `@extref` in the plotting-extension docstrings**
+  ([#427](https://github.com/control-toolbox/CTModels.jl/issues/427)). The `plot!` /
+  `Makie.plot` / `Makie.plot!` docstrings cross-referenced the public method as
+  `` [`Plots.plot(::CTModels.Solutions.Solution)`](@extref) ``, an anchor that cannot
+  exist: the public `Plots.plot` / `Makie.plot` methods on a `Solution` are defined in
+  weak-dependency extensions, so the inventory registers only the internal
+  `CTModelsPlots._plot` / `CTModelsMakie._plot` helpers. The links are now plain prose.
+  This also clears four `@extref` warnings from OptimalControl.jl's docs build, where
+  these docstrings are transcluded. Follow-on to
+  [#416](https://github.com/control-toolbox/CTModels.jl/issues/416).
+
+### ✅ Compatibility
+
+- **No breaking changes**: documentation sources only; no runtime behavior, public API,
+  or migration is affected.
+
 ## [0.19.3-beta] - unreleased
 
 ### 📚 Documentation
diff --git a/Project.toml b/Project.toml
index 4634aca3..ec8db667 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,6 +1,6 @@
 name = "CTModels"
 uuid = "34c4fa32-2049-4079-8329-de33c2a22e2d"
-version = "0.19.3-beta"
+version = "0.19.4-beta"
 authors = ["Olivier Cots <olivier.cots@toulouse-inp.fr>"]
 
 [deps]
diff --git a/ext/CTModelsMakie.jl b/ext/CTModelsMakie.jl
index 9cc90445..94d375fc 100644
--- a/ext/CTModelsMakie.jl
+++ b/ext/CTModelsMakie.jl
@@ -76,7 +76,7 @@ $(TYPEDSIGNATURES)
 Plot the components of an optimal control [`CTModels.Solutions.Solution`](@extref) with a
 Makie backend.
 
-Same `description` and keyword arguments as [`Plots.plot(::CTModels.Solutions.Solution)`](@extref)
+Same `description` and keyword arguments as the Plots-backend `plot`
 (`layout`, `control`, `time`, the `*_style` / `*_bounds_style` keywords, `color`,
 `size`). Returns a `Makie.Figure`.
 
@@ -97,8 +97,8 @@ end
 $(TYPEDSIGNATURES)
 
 Overlay the optimal control solution `sol` onto the existing `Makie.Figure` `f`. Same
-behaviour and keyword arguments as [`Plots.plot(::CTModels.Solutions.Solution)`](@extref); an
-empty `f` is filled as if by `plot`.
+behaviour and keyword arguments as the Plots-backend `plot`; an empty `f` is filled as if
+by `plot`.
 """
 function Makie.plot!(
     f::Makie.Figure, sol::CTModels.Solution, description::Symbol...; kwargs...
diff --git a/ext/CTModelsPlots.jl b/ext/CTModelsPlots.jl
index a4e30c1f..8598bb14 100644
--- a/ext/CTModelsPlots.jl
+++ b/ext/CTModelsPlots.jl
@@ -125,8 +125,7 @@ end
 $(TYPEDSIGNATURES)
 
 Overlay the optimal control solution `sol` onto the existing plot `p`. Same behaviour and
-keyword arguments as [`Plots.plot(::CTModels.Solutions.Solution)`](@extref); an empty `p` is filled as
-if by `plot`.
+keyword arguments as `plot` (documented above); an empty `p` is filled as if by `plot`.
 """
 function Plots.plot!(
     p::Plots.Plot, sol::CTModels.Solution, description::Symbol...; kwargs...