[ocots]

Plan: rewrite the documentation (#307)

Conventions: ct-conventions v0.10.0; ct-agents v0.4.0.

What and why

The site described the v1 API (direct_transcription, docp, nlp_model(docp)), and each problem page solved the problem in two modelings at build time. This PR rewrites it in the structure of #307, with problem pages generated from the files of each problem and nothing solved for them at build time.

The problem pages

Each page has a tab bar at the top, sticky under the navigation on wide screens, so the modeling is chosen instead of scrolled to:

Tab	Content
Problem	description and formulation, parameters, reference objective (per scheme: grid, solves, distinct solutions, agreement), analytic solution when known
one per modeling where the problem exists	status (a draft says why), how to get and solve it, the model as written (the @def block, or the ProblemData of JuMP) with a link to its file, and the results of each configuration (platforms, objective, gap to the reference)
Compare, only with two modelings or more	which pairs are checked to give the same NLP (or why not: a draft), results side by side, and which solution each modeling reached

• The chosen tab is in the URL (?view=JuMP) and remembered in the browser, so a JuMP user sees JuMP first on every problem.
• Generic: the pages loop over the modeling table through docs/modelings.jl, one documentation adapter per modeling (title, summary, packages, snippet, first line of the model, modeling it is checked against). The build fails if a modeling has no adapter. Adding a modeling (ModelingToolkit, [Problems] Proof of concept: a ModelingToolkit modeling, solved with Corleone, with our own bryson_denham #308) means adding one adapter.
• Results come from the crons, read from ext/MetaData/references/<problem>.toml ([Metadata] Reference objectives per scheme, computed by a script #375), which already hold every result per modeling, configuration and platform, and the distinct solutions. No ✓ or ✗ on convergence: the gap is shown as it is ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360).

The site

Section	Pages
Introduction	scope, the modelings (generated table), quick start, citing, reproducibility
Getting started	Installation (generated table "to use the modeling / the extension needs / to solve, load"; missing-extension error from a fresh process, SITE15), Your first problem, Guided tour
User guide	Get a problem, Solve with OptimalControl (descriptive, explicit, scalarized, GPU), Solve with JuMP, JuMP schemes (moved, unchanged), Initial guess (#151), Compare modelings (same NLP, one reference), Plot a solution
Problems	Overview, Browser, Status (generated: statuses, and the latest convergence reports from the results branch with what deserves a look; says so if unreachable), the problem pages
Developers	one page linking to the READMEs (decision of 2026-11-04)
API Reference	generated with with_api_reference (SITE1, SITE2, SITE3, SITE10): public page and Internals with both extensions; the problem functions are left out (their pages)
Migrating from 0.5	from BREAKING.md, with [!code --] / [!code ++] (SITE11)

Guide pages execute short code with hidden checks against the reference objectives (@assert isapprox(objective(sol), reference_objective(:beam); rtol=1e-6) # hide). They found a real trap on the first build: solve uses :midpoint by default, the references :trapeze; every snippet now gives the scheme.

Choices (narrated)

• Split with [Doc] Results pipeline for the documentation, and a gallery of problems #314. This PR writes the problem pages with the results of the reference files. [Doc] Results pipeline for the documentation, and a gallery of problems #314 keeps the plots, the freshness badge, the Reproducibility block per problem and the gallery. Until the gallery, the problem pages stay in the sidebar.
• ext/README.md written here. The Developers page links to READMEs; the main one (add a problem, add a modeling) did not exist, and adding a modeling now includes the documentation adapter of this PR.
• Plots as SVG (SITE12): done here, needed by the Plot page; overlaps [Doc] Finish the VitePress migration: plots as SVG and local InterLinks inventories #407, which keeps the local InterLinks inventories (SITE4).
• DocumenterMermaid removed: no diagram on the site, and under VitePress it printed DocumenterMermaid.MermaidScriptBlock([...]) at the bottom of every page.
• Docs environment: CTBase (API reference, repl_without_extensions), MadNLP, Downloads added; NLPModels, CTModels, FilePathsBase, DocumenterMermaid removed (unused).

Done when (#307)

• Structure in the VitePress site; old pages removed (tutorial-get.md, tutorial-solve.md, dev-add.md, dev-api.md, problems-introduction.md).

• Installation page explains each extension and what to install (generated from the adapters).

• Problem pages generated with conditional sections: two modelings or more (every problem today); one modeling and missing results shown by restricting the data in a script (no problem is in one modeling today):

  beam, 3 modelings: panels=5 compare=true
  beam, JuMP only: panels=2 compare=false tabs=[{"id":"problem",…},{"id":"JuMP",…}]
  no results: "No reference objective has been computed for this problem yet." / "No results yet for this modeling: they come from the convergence crons."
  

• User guide pages execute short code with hidden checks.

• Status page public. The gallery is [Doc] Results pipeline for the documentation, and a gallery of problems #314.

• [Doc] review of examples published on the website #229 and [Doc] Intial guess #151 closed: [Doc] Intial guess #151 is closed (the Initial guess page covers it). [Doc] review of examples published on the website #229: the old problem template is gone, so its wrong first-line comment and its printed named tuples are gone (parameters are a table now), and the Plot page draws both solutions with plot!(solution(…)) and labels; not done: the note on the MKL warning on macOS ARM (upstream). To close by the maintainer after review.

Verification

• julia --project=docs docs/make.jl: passes, 102 s for the whole site (the old build solved every problem twice). Remaining warnings: undocumented internals skipped by the API reference, no logo or favicon (expected).
• JuliaFormatter (blue) on the Julia files of docs/; typos clean.
• Screenshots checked: problem tab, modeling tab, Compare (beam, mountain_car with its two local solutions), Status, dark mode, a draft modeling (bryson_denham, JuMP), 500 px width.
• Not verified: the sticky bar while scrolling (headless captures with an anchor come out blank). To check by hand in the preview.

Out of scope

Plots, freshness, Reproducibility per problem, gallery (#314); visualize (#134); JuMP costate signs (#326, mentioned on the Plot page); InterLinks inventories (#407).

Labels

run documentation to build the site in CI.

Refs #307

🤖 Generated with Claude Code