docs: Makie plotting page (phase L) - #935
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
OptimalControlre-exports Plots'plot/plot!unconditionally, so a session with a Makie backend loaded has no backend-neutral call to write: bareplotraisesUndefVarError. The page opens on exactly that error, live.results/plot.mdmeasured to work onMakie.plot), so a parallel reference would only drift. The new page carries the delta only.flows/*.mdneeds 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 — andMakie.plot!(ax, sol), the call a Plots reader reaches for, fails. The page shows it failing, then the fix.results/plot.mdgains 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, notusing— avoids the exactplot/plot!clash this page teaches, biting at build level). This PR only adds the page and:docs/make.jl;CTModelsMakie/CTFlowsMakieregistered in the extension-docstring loop, so the page's Reference section resolves (spelledCairoMakie.Makie.plot(…)—Makieis not a bare name inMainunderimport CairoMakie).Verified
@ref(baseline since docs: render CairoMakie figures as SVG, like Plots #933) — unchanged.Error:-level log lines are pre-existing@extrefnoise already underwarnonly=[:cross_references, :external_cross_references](Phase D):CTModelsMakie's own docstrings carry the same broken upstream@extreftoPlots.plot(::CTModels.Solutions.Solution)thatresults/plot.mdalready tolerates viaCTModelsPlots. +2 instances, same class, not a new category..pngindocs/build/1/results/beyond the static site logo (#933's invariant holds)."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 documentationto build the site here.🤖 Generated with Claude Code