control-toolbox · ocots · Sep 2, 2026 · Sep 2, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -42,6 +42,8 @@ Dependency realignment onto the released control-toolbox ecosystem, the v2.0 →
 
 - **`_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/docs/make.jl b/docs/make.jl
@@ -127,14 +127,17 @@ cp(
 # ═══════════════════════════════════════════════════════════════════════════════
 # Configuration
 # ═══════════════════════════════════════════════════════════════════════════════
-# if draft is true, then the julia code from .md is not executed
-# to disable the draft mode in a specific markdown file, use the following:
+# `draft = false` is the committed default: every page executes its `@example` /
+# `@repl` blocks, which is what a published build must do. Flip this to `true`
+# locally for a fast build that skips all execution (checking navigation, links,
+# `@extref`/`@ref` resolution, rendering). To keep one specific page drafted while
+# the rest execute, add to its `@meta` block:
 #=
 ```@meta
-Draft = false
+Draft = true
 ```
 =#
-draft = true  # Draft mode: skip @example execution globally; guided tour overrides below
+draft = false
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # Load extensions
@@ -235,17 +238,10 @@ mkpath(JL_OUTPUT)
 
 for file in ["guided-tour.jl"]
     INPUT = joinpath(LITERATE_DIR, file)
-    # The guided tour executes like every other real page: inject `Draft = false`
-    # into the generated page's `@meta` block so its code runs under the global
-    # `draft = true` (Phase E5). The PR-2-era comment here claimed executing it
-    # "surfaced several unrelated runtime bugs" — those were upstream and have
-    # since been fixed; the tour now builds clean.
-    add_draft_false =
-        content -> replace(
-            content,
-            "EditURL = \"../../src-literate/$file\"\n" => "EditURL = \"../../src-literate/$file\"\nDraft = false\n",
-        )
-    Literate.markdown(INPUT, MD_OUTPUT; name="guided-tour", postprocess=add_draft_false)
+    # The guided tour executes like every other real page under the global
+    # `draft = false`. (It once carried an injected `Draft = false` override to run
+    # under a `draft = true` default; that default is gone.)
+    Literate.markdown(INPUT, MD_OUTPUT; name="guided-tour")
     Literate.notebook(INPUT, NB_OUTPUT; name="guided-tour", execute=false)
     Literate.script(INPUT, JL_OUTPUT; name="guided-tour")
 end
@@ -273,14 +269,10 @@ with_api_reference(src_dir, ext_dir) do api_pages
         # 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
-        # api/modelling.md) is a side effect of `draft` mode skipping execution and is never
-        # added to `doc.internal.errors` — confirmed by testing that a genuinely broken
-        # @example block on a Draft=false page (this file rewritten to error) still fails the
-        # build with :example_block even with this exact warnonly list, while the CTParser one
-        # stays silent either way. Excluding :example_block would have hidden real breakage for
-        # no benefit.
+        # :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],
         sitename="OptimalControl.jl",
         format=DocumenterVitepress.MarkdownVitepress(;

diff --git a/docs/src/examples/control-and-variable.md b/docs/src/examples/control-and-variable.md
@@ -1,9 +1,5 @@
 # [Control and variable together](@id examples-control-and-variable)
 
-```@meta
-Draft = false
-```
-
 The same two systems as [Parameter estimation without a control](@ref examples-control-free),
 now with a control input and a quadratic control cost — estimating a parameter *and* a control
 at the same time. Read that page first; this one skips the narration that doesn't change.

diff --git a/docs/src/examples/control-free.md b/docs/src/examples/control-free.md
@@ -1,9 +1,5 @@
 # [Parameter estimation without a control](@id examples-control-free)
 
-```@meta
-Draft = false
-```
-
 Two problems with no control anywhere — only a `variable` to fit to data. See
 [No control](@ref modelling-without-control) for the modelling side of this;
 this page is the full worked story, direct and indirect, for both.

diff --git a/docs/src/examples/double-integrator-energy.md b/docs/src/examples/double-integrator-energy.md
@@ -1,9 +1,5 @@
 # [Energy minimisation](@id examples-double-integrator-energy)
 
-```@meta
-Draft = false
-```
-
 The double integrator — a unit mass sliding frictionlessly on a rail, acceleration as the
 control — transferred between two rest states at minimal energy. The simplest problem on this
 site, and the same one used to introduce the package on the home page.

diff --git a/docs/src/examples/double-integrator-time.md b/docs/src/examples/double-integrator-time.md
@@ -1,9 +1,5 @@
 # [Time minimisation (bang–bang)](@id examples-double-integrator-time)
 
-```@meta
-Draft = false
-```
-
 Same wagon as [Energy minimisation](@ref examples-double-integrator-energy), but transferred
 **as fast as possible** instead of at minimal energy — a bounded control gives a bang–bang
 optimal law with a single switch.

diff --git a/docs/src/examples/gallery.md b/docs/src/examples/gallery.md
@@ -1,9 +1,5 @@
 # [Example gallery](@id examples-gallery)
 
-```@meta
-Draft = false
-```
-
 A guide answers *"how do I do X"*; an example answers *"what does a real problem look like"*.
 Each page here is a complete, self-contained problem worked end to end — a story with a
 result, not a feature demonstration.

diff --git a/docs/src/examples/logo.md b/docs/src/examples/logo.md
@@ -1,9 +1,5 @@
 # [The logo](@id examples-logo)
 
-```@meta
-Draft = false
-```
-
 The OptimalControl.jl logo is not a drawing. It is the solution of an optimal control
 problem — an **energy-minimal low-thrust orbit transfer** — solved once and repeated by
 symmetry.

diff --git a/docs/src/examples/singular-control.md b/docs/src/examples/singular-control.md
@@ -1,9 +1,5 @@
 # [Singular control](@id examples-singular-control)
 
-```@meta
-Draft = false
-```
-
 A vehicle in the plane with drift, time-optimal, whose extremal control is neither $+1$ nor
 $-1$ on part of the trajectory — a **singular arc**. This is the problem the whole
 [Geometry](@ref geometry-overview) section exists to support: computing that arc's control

diff --git a/docs/src/examples/state-constraint.md b/docs/src/examples/state-constraint.md
@@ -1,9 +1,5 @@
 # [State constraint](@id examples-state-constraint)
 
-```@meta
-Draft = false
-```
-
 The double integrator again, this time with a state constraint active on part of the
 trajectory — a boundary arc, a costate jump, and (for the second problem below) a genuine
 multi-arc structure.

diff --git a/docs/src/examples/turnpike.md b/docs/src/examples/turnpike.md
@@ -1,9 +1,5 @@
 # [Turnpike (bang–singular–bang)](@id examples-turnpike)
 
-```@meta
-Draft = false
-```
-
 A scalar system, $\dot x = u$ with $u \in [-1,1]$, driven between two states over a fixed
 horizon while minimising $\int x^2$. Because the cost is linear in $u$, the optimal control is
 bang — $u = \pm 1$ — except on an interval where the switching function vanishes: a **singular

diff --git a/docs/src/flows/accessors.md b/docs/src/flows/accessors.md
@@ -1,9 +1,5 @@
 # [Accessors](@id flows-accessors)
 
-```@meta
-Draft = false
-```
-
 Building a flow doesn't throw away what it was built from — a flow remembers its Hamiltonian,
 its vector field, the control law you passed in, and the underlying integrator. This page is
 the map of what you can pull back out, and from which kind of flow.

diff --git a/docs/src/flows/constrained-arcs.md b/docs/src/flows/constrained-arcs.md
@@ -1,9 +1,5 @@
 # [Constrained arcs](@id flows-constrained-arcs)
 
-```@meta
-Draft = false
-```
-
 A flow along a boundary arc — where a state constraint is active — needs the constraint and
 its multiplier, not just the control law.
 

diff --git a/docs/src/flows/from-hamiltonians.md b/docs/src/flows/from-hamiltonians.md
@@ -1,9 +1,5 @@
 # [From Hamiltonians](@id flows-from-hamiltonians)
 
-```@meta
-Draft = false
-```
-
 Every constructor below builds a flow **without** an OCP — the building blocks
 [From an OCP](@ref flows-from-ocp) is itself assembled from. One section per constructor.
 

diff --git a/docs/src/flows/from-ocp.md b/docs/src/flows/from-ocp.md
@@ -1,9 +1,5 @@
 # [From an OCP](@id flows-from-ocp)
 
-```@meta
-Draft = false
-```
-
 The main path: you've worked out the PMP's maximising control $u^*(t,x,p,v)$ by hand, and want
 the Hamiltonian flow it defines.
 

diff --git a/docs/src/flows/multi-phase.md b/docs/src/flows/multi-phase.md
@@ -1,9 +1,5 @@
 # [Multi-phase flows](@id flows-multi-phase)
 
-```@meta
-Draft = false
-```
-
 Bang-bang switchings, jumps at a boundary arc's entry/exit, phase changes of any kind: a
 sequence of flows, each active on its own sub-interval, concatenated into one callable object —
 itself a flow.

diff --git a/docs/src/flows/overview.md b/docs/src/flows/overview.md
@@ -1,9 +1,5 @@
 # [Overview](@id flows-overview)
 
-```@meta
-Draft = false
-```
-
 `Flow` is one constructor that does three distinct jobs: **indirect optimal control** (build
 the Hamiltonian flow of the Pontryagin Maximum Principle, write a shooting function, solve it),
 **simulation** (integrate a controlled system under an open-loop or feedback control), and

diff --git a/docs/src/flows/shooting.md b/docs/src/flows/shooting.md
@@ -1,9 +1,5 @@
 # [Shooting](@id flows-shooting)
 
-```@meta
-Draft = false
-```
-
 The payoff of everything else in this section: turn a flow into a root-finding problem for the
 unknown initial costate (and switching times, and free final time), and solve it.
 

diff --git a/docs/src/flows/simulation.md b/docs/src/flows/simulation.md
@@ -1,9 +1,5 @@
 # [Simulation](@id flows-simulation)
 
-```@meta
-Draft = false
-```
-
 Sometimes you don't want an optimum — you have a controlled system and a specific control
 (open-loop or feedback), and you want the trajectory it produces.
 

diff --git a/docs/src/geometry/ad-backend.md b/docs/src/geometry/ad-backend.md
@@ -1,9 +1,5 @@
 # [AD backend](@id geometry-ad-backend)
 
-```@meta
-Draft = false
-```
-
 ```@example main
 using OptimalControl
 ```

diff --git a/docs/src/geometry/ad.md b/docs/src/geometry/ad.md
@@ -1,9 +1,5 @@
 # [Lie derivative and Lie bracket](@id geometry-ad)
 
-```@meta
-Draft = false
-```
-
 `ad(X, foo)` is one function with two meanings, chosen by what `foo` returns.
 
 ```@example main

diff --git a/docs/src/geometry/lie-macro.md b/docs/src/geometry/lie-macro.md
@@ -1,9 +1,5 @@
 # [The `@Lie` macro](@id geometry-lie-macro)
 
-```@meta
-Draft = false
-```
-
 `@Lie` lets you write brackets the way you'd write them on paper: square brackets for a Lie
 bracket, curly braces for a Poisson bracket.
 

diff --git a/docs/src/geometry/lift.md b/docs/src/geometry/lift.md
@@ -1,9 +1,5 @@
 # [Lift](@id geometry-lift)
 
-```@meta
-Draft = false
-```
-
 Given a vector field $X : \mathbb{R}^n \to \mathbb{R}^n$, its **lift** is the Hamiltonian
 
 ```math

diff --git a/docs/src/geometry/overview.md b/docs/src/geometry/overview.md
@@ -1,9 +1,5 @@
 # [Overview](@id geometry-overview)
 
-```@meta
-Draft = false
-```
-
 Some flows can't be built directly from an optimal control problem — the control law itself
 has to be *derived* first, for example a singular control on an arc where the usual
 maximization condition degenerates. Deriving it needs differential-geometry tools: Lie

diff --git a/docs/src/geometry/poisson.md b/docs/src/geometry/poisson.md
@@ -1,9 +1,5 @@
 # [Poisson bracket](@id geometry-poisson)
 
-```@meta
-Draft = false
-```
-
 For two Hamiltonians $H, G$,
 
 ```math

diff --git a/docs/src/getting-started/first-problem.md b/docs/src/getting-started/first-problem.md
@@ -1,9 +1,5 @@
 # [Your first problem](@id getting-started-first-problem)
 
-```@meta
-Draft = false
-```
-
 The shortest complete story: define a problem, solve it, look at the result. Fifteen lines,
 no options, no theory.
 

diff --git a/docs/src/getting-started/installation.md b/docs/src/getting-started/installation.md
@@ -1,9 +1,5 @@
 # [Installation](@id getting-started-installation)
 
-```@meta
-Draft = false
-```
-
 ## Install
 
 Open Julia's [interactive session (REPL)](https://docs.julialang.org/en/v1/manual/getting-started)

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,9 +1,5 @@
 # OptimalControl.jl
 
-```@meta
-Draft = false
-```
-
 The OptimalControl.jl package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox). The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods, both on CPU and GPU.
 
 ## Motivation

diff --git a/docs/src/migration.md b/docs/src/migration.md
@@ -1,9 +1,5 @@
 # [Migrating to v2.1](@id migration)
 
-```@meta
-Draft = false
-```
-
 !!! note "This page does not execute"
 
     Unlike every other page on this site, the code blocks here deliberately show **spellings

diff --git a/docs/src/modelling/abstract-syntax.md b/docs/src/modelling/abstract-syntax.md
@@ -1,9 +1,5 @@
 # [Abstract syntax (`@def`)](@id modelling-abstract-syntax)
 
-```@meta
-Draft = false
-```
-
 The full grammar of OptimalControl.jl's small *Domain Specific Language* is given below. The idea is to use a syntax that is
 
 - pure Julia (and, as such, effortlessly analysed by the standard Julia parser),

diff --git a/docs/src/modelling/formulation.md b/docs/src/modelling/formulation.md
@@ -1,9 +1,5 @@
 # [Formulation](@id modelling-formulation)
 
-```@meta
-Draft = false
-```
-
 An optimal control problem (OCP) with fixed initial and final times can be described as minimising the cost functional (in Bolza form)
 
 ```math

diff --git a/docs/src/modelling/functional-api.md b/docs/src/modelling/functional-api.md
@@ -1,9 +1,5 @@
 # [Functional API](@id modelling-functional-api)
 
-```@meta
-Draft = false
-```
-
 The [`@def`](@ref) macro provides a concise DSL to define optimal control problems. An alternative is the **functional API**, which builds the same problem step by step using plain Julia functions.
 
 The functional API uses `OptimalControl.PreModel` as a mutable builder, populated by setter calls, then frozen into an immutable `OptimalControl.Model` by [`build`](@ref). Both `PreModel` and `Model` are imported, not exported — write `OptimalControl.PreModel()`.

diff --git a/docs/src/modelling/inspect.md b/docs/src/modelling/inspect.md
@@ -1,9 +1,5 @@
 # [Inspect a problem](@id modelling-inspect)
 
-```@meta
-Draft = false
-```
-
 Once a problem is built — via [`@def`](@ref) or the [functional API](@ref modelling-functional-api) — every part of it can be read back: dimensions, names, dynamics, costs, constraints, traits. This page is about reading a model, not solving it: for that, see [Solve overview](@ref solve-overview); for the indirect/PMP route, see [Flows overview](@ref flows-overview).
 
 !!! note "Signatures and `is_*` aliases"

diff --git a/docs/src/modelling/with-ai.md b/docs/src/modelling/with-ai.md
@@ -1,9 +1,5 @@
 # [With AI](@id modelling-with-ai)
 
-```@meta
-Draft = false
-```
-
 Using now common models from AI, it is an elementary task to have such an agent learn the syntax of OptimalControl.jl DSL, then use the agent to translate standard math into this DSL. Here is a typical prompt, pointing to the [abstract syntax](@ref modelling-abstract-syntax):
 
 ```text