Skip to content

docs: Makie plotting page (phase L) - #935

Merged
ocots merged 1 commit into
mainfrom
docs/makie
Sep 1, 2026
Merged

docs: Makie plotting page (phase L)#935
ocots merged 1 commit into
mainfrom
docs/makie

Conversation

@ocots

@ocots ocots commented Sep 1, 2026

Copy link
Copy Markdown
Member

What

Adds results/plot-makie.md, the contrast page for the Makie backend beside the existing Plots reference (results/plot.md). Plan: .reports/campaign/L-makie-docs.md.

Why this shape

Hub + contrast, not a generic page or two parallel references — decided on three measurements:

  • OptimalControl re-exports Plots' plot/plot! unconditionally, so a session with a Makie backend loaded has no backend-neutral call to write: bare plot raises UndefVarError. The page opens on exactly that error, live.
  • Keyword parity between the two backends is total (every keyword on results/plot.md measured to work on Makie.plot), so a parallel reference would only drift. The new page carries the delta only.
  • flows/*.md needs no edit — both flow trajectory kinds already plot correctly through the same call.

The core idea the page teaches

plot/plot! are a Plots-shaped convenience API that build a whole figure in one call — not the backend itself. Customising means dropping to the backend's own commands through the panel: plt[i] on Plots, f.content[i] on Makie.

On Plots, plot! does double duty (overlay a solution and add a native series, same function). On Makie the two roles split — Makie.plot!(f, sol) is solution overlay, lines!(ax, …) is a native addition — and Makie.plot!(ax, sol), the call a Plots reader reaches for, fails. The page shows it failing, then the fix.

results/plot.md gains a short "Choosing a backend" pointer plus a native-annotation example in its existing Custom subplots section, so both pages state the same idea in their own backend.

Build plumbing

SVG rendering for Makie figures already shipped in #933 (import CairoMakie, not using — avoids the exact plot/plot! clash this page teaches, biting at build level). This PR only adds the page and:

  • a nav entry after "Plot" in docs/make.jl;
  • CTModelsMakie / CTFlowsMakie registered in the extension-docstring loop, so the page's Reference section resolves (spelled CairoMakie.Makie.plot(…)Makie is not a bare name in Main under import CairoMakie).

Verified

  • Build exit 0.
  • 0 unresolved @ref (baseline since docs: render CairoMakie figures as SVG, like Plots #933) — unchanged.
  • The only Error:-level log lines are pre-existing @extref noise already under warnonly=[:cross_references, :external_cross_references] (Phase D): CTModelsMakie's own docstrings carry the same broken upstream @extref to Plots.plot(::CTModels.Solutions.Solution) that results/plot.md already tolerates via CTModelsPlots. +2 instances, same class, not a new category.
  • No .png in docs/build/1/results/ beyond the static site logo (#933's invariant holds).
  • 7 SVG figures render on the new page, sizes consistent with content (the 5-panel constrained-problem figure is largest, the single-panel custom figure smallest); the annotated "after" figure visibly contains the "switch" text label and 8 dashed strokes (control bounds + switching marker) — confirmed in the SVG source.
  • docs/src/assets/ unchanged (no compat move in this phase).

CI documentation builds are label-gated — add run documentation to build the site here.

🤖 Generated with Claude Code

Adds results/plot-makie.md, the contrast page for the Makie backend
beside the existing Plots reference (results/plot.md). Hub + contrast
shape, decided against a generic page or two parallel references:
OptimalControl re-exports Plots' plot/plot! unconditionally, so a
Makie session has no backend-neutral call to write — bare `plot`
raises UndefVarError once a Makie backend is loaded, and the page
opens on exactly that. Keyword parity with results/plot.md is total
(measured), so the new page carries the delta only.

The core idea the page teaches: plot/plot! are a Plots-shaped
convenience API that builds a whole figure in one call; customising
means dropping to the backend's own commands through the panel
(plt[i] on Plots, f.content[i] on Makie). On Plots, plot! does double
duty (overlay a solution and add a native series); on Makie the roles
split (Makie.plot!(f, sol) vs lines!(ax, ...)), and Makie.plot!(ax,
sol) — the call a Plots reader reaches for — fails. Shown failing,
with the fix.

results/plot.md gains a short "Choosing a backend" pointer and a
native-annotation example in its existing Custom subplots section, so
both pages state the same idea in their own backend.

docs/make.jl: nav entry after "Plot"; CTModelsMakie/CTFlowsMakie
registered in the extension-docstring loop so the page's Reference
section resolves (spelled CairoMakie.Makie.plot(...) - Makie is not a
bare name in Main under #933's `import CairoMakie`).

SVG plumbing for Makie figures already shipped in #933; this phase
only adds the page. Build verified: exit 0, 0 unresolved @ref (only
pre-existing @extref noise already under warnonly, +2 instances from
transcluding CTModelsMakie's own upstream-broken @extref, same class
already present on results/plot.md), no .png beyond the static site
logo, 7 SVG figures rendering correctly including the annotated
before/after pair.

Plan: .reports/campaign/L-makie-docs.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ocots
ocots merged commit f93cd4f into main Sep 1, 2026
3 checks passed
@ocots
ocots deleted the docs/makie branch September 1, 2026 17:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant