diff --git a/BREAKING.md b/BREAKING.md index 800e9c3c3..359cfe3da 100644 --- a/BREAKING.md +++ b/BREAKING.md @@ -4,12 +4,27 @@ Chronological, newest first. Each `CHANGELOG.md` entry links back here for the f record; this file never duplicates a release's own compat table, only what a caller must change or be aware of. +- [Non-breaking notes (2.2.1-beta)](#non-breaking-notes-221-beta) - [Non-breaking notes (2.2.0-beta)](#non-breaking-notes-220-beta) - [Breaking changes: v2.0 → v2.1.0-beta](#breaking-changes-v20--v210-beta) - [Breaking changes: v1.x → v2.0](#breaking-changes-v1x--v20) --- +## Non-breaking notes (2.2.1-beta) + +Documentation infrastructure only. **Nothing to migrate** — OptimalControl's API and runtime +behaviour are unchanged, and the change is invisible to anyone who only *uses* the package. + +For contributors who build the documentation locally: + +- `docs/make.jl` now defaults to `draft = false`, so every page executes its `@example` / + `@repl` blocks. Set `draft = true` in `make.jl` for a fast local build that skips + execution; opt a single page out of execution with `Draft = true` in its `@meta` block. +- The docs build has no `warnonly` fallback any more: an unresolved `@ref` / `@extref`, or a + broken `@example` / `@repl`, now fails the build rather than warning. +- The docs environment moves to CTBase `0.30.4-beta` and CTModels `0.19.4-beta`. + ## Non-breaking notes (2.2.0-beta) ### `using ExaModels` now clashes with OptimalControl diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ed1714d0..d62669594 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,26 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). --- +## [2.2.1-beta] — 2026-09-02 + +Documentation-infrastructure follow-up to the 2.2.0-beta site rewrite. No change to OptimalControl's API or runtime behaviour; nothing to migrate — see [BREAKING.md](BREAKING.md). + +### 📚 Documentation + +- **The docs build resolves every `@extref` and `@ref`.** Two long-standing backlogs closed: + - `_strategy_parameter` 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 ([#944](https://github.com/control-toolbox/OptimalControl.jl/pull/944)). + - the four `Plots.plot(::CTModels.Solutions.Solution)` `@extref` links were CTModels' plotting-extension docstrings referencing an anchor that cannot exist (extension methods are not in any inventory); fixed upstream and shipped in [CTModels 0.19.4-beta](https://github.com/control-toolbox/CTModels.jl/pull/428). + +- **`makedocs` no longer sets `warnonly`** ([#952](https://github.com/control-toolbox/OptimalControl.jl/pull/952)). With both backlogs cleared — the `@ref`/`DOCPCache` pair ([CTDirect#630](https://github.com/control-toolbox/CTDirect.jl/issues/630)) and the `@extref` set above — an unresolved cross-reference now fails the build instead of warning. Verified with the sibling inventories resolved remotely, as on CI. + +- **`docs/make.jl` runs `draft = false` by default** ([#949](https://github.com/control-toolbox/OptimalControl.jl/pull/949)). The build used to ship `draft = true` globally with a `@meta Draft = false` block repeated in 43 pages to opt each one back into execution — a double negative that also blocked a fast `draft = true` pass for link/nav checks. Now the default executes every page; flip the one flag in `make.jl` for a fast local build, or set `Draft = true` in a single page's `@meta` to exclude it. The guided-tour `Draft = false` Literate injection is removed. + +- **The local sibling `objects.inv` path is only tried outside CI** ([#951](https://github.com/control-toolbox/OptimalControl.jl/pull/951)) — CI never has the sibling repos checked out, so it was logging seven `Failed to load inventory` warnings on every run before falling back to the remote inventory. Local-dev ordering (local-first) is unchanged. + +### 📦 Dependencies + +- Picks up **CTBase `0.30.4-beta`** (`Descriptions` error-message fixes, re-exported) and **CTModels `0.19.4-beta`** (the `@extref` docstring fix). `docs/src/assets/Manifest.toml` regenerated to match. + ## [2.2.0-beta] — 2026-08-28 Dependency realignment onto the released control-toolbox ecosystem, the v2.0 → v2.1 compatibility shims, and a full documentation-site rewrite. No breaking change to OptimalControl's own API; two near-breaking notes — see [BREAKING.md](BREAKING.md). @@ -40,10 +60,6 @@ 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). - -- **`docs/make.jl` runs `draft = false` by default** ([#948](https://github.com/control-toolbox/OptimalControl.jl/issues/948)). The build used to ship `draft = true` globally with a `@meta Draft = false` block repeated in 43 pages to opt each one back into execution — a double negative that also blocked a fast `draft = true` pass for link/nav checks. Now the default executes every page; flip the one flag in `make.jl` for a fast local build, or set `Draft = true` in a single page's `@meta` to exclude it. The guided-tour `Draft = false` Literate injection is removed. - ### 📦 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/Project.toml b/Project.toml index 7022e906c..ad776d915 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "OptimalControl" uuid = "5f98b655-cc9a-415a-b60e-744165666948" -version = "2.2.0-beta" +version = "2.2.1-beta" authors = ["Olivier Cots "] [deps] diff --git a/docs/api-coverage.md b/docs/api-coverage.md index a2dc426e1..71ec71e8f 100644 --- a/docs/api-coverage.md +++ b/docs/api-coverage.md @@ -1,8 +1,8 @@ # API coverage matrix **Status**: living cross-reference · **Measured against**: `names(OptimalControl)` on -OptimalControl 2.2.0-beta (`[compat]` floors CTBase 0.30, CTModels 0.19, CTFlows 0.18, -CTLie 0.2, CTSolvers 0.5, CTDirect 1, CTParser 0.9) +OptimalControl 2.2.1-beta (`[compat]` floors CTBase 0.30, CTModels 0.19, CTFlows 0.18, +CTLie 0.2, CTSolvers 0.5, CTDirect 1, CTParser 0.9) — unchanged from 2.2.0-beta ## What this is diff --git a/docs/make.jl b/docs/make.jl index 0644b029a..67e85ea63 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -247,21 +247,13 @@ 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 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: with `draft = false` every page - # executes, and a genuinely broken `@example` / `@repl` block must fail the build. - # Verified: an error introduced into any executing block still fails with - # :example_block under this exact warnonly list. - warnonly=[:cross_references, :external_cross_references], + # No `warnonly`: every unresolved cross-reference fails the build. The historical + # backlog is cleared — the `@ref`/`DOCPCache` pair (control-toolbox/CTDirect.jl#630, + # closed) and the `@extref` set (`CTBase.Strategies.parameter` #943; CTModels' + # extension docstrings control-toolbox/CTModels.jl#427, shipped in CTModels + # 0.19.4-beta). With `draft = false` a broken `@example` / `@repl` also fails + # (:example_block). Verified with the sibling inventories resolved remotely (as on + # CI). See .reports/campaign/D-api-reference.md. sitename="OptimalControl.jl", format=DocumenterVitepress.MarkdownVitepress(; repo=repo_url, devbranch="main", devurl="dev", sidebar_drawer=true diff --git a/docs/src/assets/Manifest.toml b/docs/src/assets/Manifest.toml index 424e4be25..2bc8b3bc7 100644 --- a/docs/src/assets/Manifest.toml +++ b/docs/src/assets/Manifest.toml @@ -301,9 +301,9 @@ version = "0.2.2-beta" [[deps.CTModels]] deps = ["CTBase", "DocStringExtensions", "LinearAlgebra", "MLStyle", "MacroTools", "OrderedCollections", "Parameters", "RecipesBase"] -git-tree-sha1 = "5906f713c5443c89fc897b3be4b8e2945cf9b1a7" +git-tree-sha1 = "007472ded070a4ebfa4dedec8074608a139225f1" uuid = "34c4fa32-2049-4079-8329-de33c2a22e2d" -version = "0.19.3-beta" +version = "0.19.4-beta" weakdeps = ["JLD2", "JSON3", "Makie", "Plots"] [deps.CTModels.extensions] @@ -2808,9 +2808,9 @@ version = "3.7.2" [[deps.SPRAL_jll]] deps = ["Artifacts", "CompilerSupportLibraries_jll", "Hwloc_jll", "JLLWrappers", "Libdl", "METIS_jll", "libblastrampoline_jll"] -git-tree-sha1 = "139fa63f03a16b3d859d925ee9149dfc15f21ece" +git-tree-sha1 = "b78d602475715c9c6ea21c9650fa5dba58e9945b" uuid = "319450e9-13b8-58e8-aa9f-8fd1420848ab" -version = "2025.9.18+0" +version = "2025.9.18+1" [[deps.SciMLBase]] deps = ["ADTypes", "Accessors", "Adapt", "ArrayInterface", "CommonSolve", "ConstructionBase", "Distributed", "DocStringExtensions", "EnumX", "FindFirstFunctions", "FunctionWrappersWrappers", "IteratorInterfaceExtensions", "LinearAlgebra", "Logging", "LoggingExtras", "Markdown", "PreallocationTools", "PrecompileTools", "Preferences", "Printf", "Random", "RecipesBase", "RecursiveArrayTools", "RuntimeGeneratedFunctions", "SciMLOperators", "SciMLPublic", "SciMLStructures", "StaticArraysCore", "Statistics", "SymbolicIndexingInterface"]