Skip to content

[Doc] Rewrite the documentation: getting started, user guide, problems, developers #307

Closed
3 of 3 issues completed

Description

@ocots

Agents: read the guide for agents in #310 first (order, difficulty, how to claim an issue, working method). The specification is in this description and in the comments below.

Updated on 2026-11-06 after #360 (convergence is reported, not tested) and #375 (reference objectives). Where an older comment contradicts this description, the description wins; what changed is listed in the update comment.

Goal

Rewrite the documentation for the new package: continuous problems (#283), per-modeling lists and statuses (#303), JuMP schemes (#284), metadata (#306), results pipeline and gallery (#314). Most of today's content describes the v1 API (direct_transcription, docp, nlp_model(docp)) and is rewritten, not patched. English (GEN1).

Part of #310, step 6. Order: after the mechanical migration to VitePress (#311), so that the new content is written once, directly in the VitePress structure; #314 in parallel.

References

  • OptimalControl.jl dev documentation, https://control-toolbox.org/OptimalControl.jl/dev/ (the stable site is not up to date): structure (Getting started → usage sections → Examples gallery → API → migration page), the Installation page ("you will also need…", table "to do X, load Y"), the gallery table (story / introduces), hidden checks (@assert isapprox(objective(sol), 6; rtol=1e-3) # hide, used in 36 pages).
  • CTBase.jl and CTFlows.jl documentation: Getting Started, guides by topic, developer notes, API Reference.
  • ct-conventions rules/site.md (SITE1–SITE18).

Current state

Six hand-written pages (index.md, problems-introduction.md, tutorial-get.md, tutorial-solve.md, dev-add.md, dev-api.md), generated problem pages (docs/problems.jl) and the browser (docs/browser.jl). The problem page template assumes both OptimalControl and JuMP exist and solves both at build time.

Structure

Section Pages
Home VitePress home page
Getting started Installation: what to install for what, as a table (OptimalControl modeling: OptimalControl and a solver package; GPU: MadNLPGPU, CUDA, CUDSS; JuMP: JuMP and Ipopt; Corleone: its package, #308; plots: Plots), explaining that each modeling is an extension; Your first problem; Guided tour
User guide Get a problem (lists per modeling, statuses, parameters, features); Solve with OptimalControl (descriptive and explicit modes, GPU); Solve with JuMP (schemes, ordering, getting a Solution); Initial guess (#151, and how to override it); Compare modelings (same NLP, #284; solutions are not compared: two solves are two optimization paths); Plot and visualize (plot(sol), plot!, visualize, #175, #134)
Problems Overview (modelings, statuses, metadata, reference objective and how it is computed, references); Gallery (#314); Status (public: statuses per modeling, and the latest convergence report of the cron, #305: solver status and gap to the reference per configuration, change since the previous run; no pass/fail on convergence); one page per problem, reached from the gallery, not listed in the sidebar
Developers Add a problem (checklist, from :draft to :valid, what is automatic, which tests run); Tests and CI (the three kinds of tests of #360: does not break, model equivalence, convergence report; environments, labels run ci …, test …, test convergence, #304); Crons and automatic issues (#305); Results pipeline (#314)
API Reference generated with with_api_reference (SITE1, SITE2, SITE10): problems, metadata, status, Problem and its API, backends, features, visualize. The generated docstrings of each problem go on its page, not in the API Reference
Migrating from 0.5 short page, low priority: the breaking changes of 0.6, taken from BREAKING.md

The word "tutorial" is not used.

Problem page

Generated from one template; each section appears only if its content exists (a problem may exist in OptimalControl only, in JuMP only, with or without Corleone):

  1. Header: name, status badge per modeling, tags, freshness of the results ([Doc] Results pipeline for the documentation, and a gallery of problems #314).
  2. Description and mathematical formulation (ext/Descriptions/<p>.md).
  3. Parameters and features ([Metadata] Computed features, reference objective, shared initial guess #306).
  4. Get and solve: one tab per available modeling (VitePress ::: code-group), short code, not executed beyond trivial calls.
  5. Results (from result.json, [Doc] Results pipeline for the documentation, and a gallery of problems #314, produced by the convergence cron): table per modeling and configuration with the solver status, the objective, the iterations, the time and the relative gap to the reference objective ([Metadata] Reference objectives per scheme, computed by a script #375), with how the reference was computed. No ✓ or ✗ on convergence and no tolerance ([Tests] Report convergence instead of testing it; keep hard checks for breakage and model equivalence #360): the gap is shown as it is. ✓ or ✗ only for what is tested: does not break, model equivalence. The build never fails on them.
  6. Plots: available solutions overlaid; visualize.svg when it exists.
  7. Comparison, only if the problem is :valid in at least two modelings: NLP equivalence status ([Paper] JuMP models for Euler, trapeze and midpoint, and NLP equivalence tests #284). Not the gap between the objectives of two modelings: that compares two optimization paths, not two models; each configuration's gap to the reference is in the results.
  8. Reproducibility block ([Doc] Results pipeline for the documentation, and a gallery of problems #314).

Executed code

Also closes

Done when

  • Structure above in the VitePress site; old pages removed.
  • Installation page explains each extension and what to install.
  • Problem pages generated with conditional sections; shown on a problem with one modeling, one with two, one with missing results.
  • User guide pages execute short code with hidden checks.
  • Status page public; gallery links to it.
  • [Doc] review of examples published on the website #229 and [Doc] Intial guess #151 closed.

Activity

  1. ocots commented on Nov 4, 2026

    @ocots
    MemberAuthor

    Additions (decided in #305):

  2. ocots commented on Nov 4, 2026

    @ocots
    MemberAuthor

    Updates:

  3. changed the title [-][Doc] Documentation for v2 and per-modeling lists[/-] [+][Doc] Rewrite the documentation: getting started, user guide, problems, developers[/+] on Nov 4, 2026
  4. ocots commented on Nov 4, 2026

    @ocots
    MemberAuthor

    Every modeling handled generically (OptimalControl, OptimalControlScalarized, JuMP, and Corleone later, #308):

  5. ocots commented on Nov 4, 2026

    @ocots
    MemberAuthor

    Correction: where this issue says "Corleone" as a modeling, read ModelingToolkit (ModelingToolkitBackend, #308): the problem is a ModelingToolkit system, and the documentation adapter shows how to get it and solve it with Corleone. Installation page: ModelingToolkit for the modeling, Corleone to solve it.

  6. ocots commented on Nov 4, 2026

    @ocots
    MemberAuthor

    Decision: Developers section = one generic page + READMEs next to the code.

    Instead of four hand-written pages (Add a problem, Tests and CI, Crons and automatic issues, Results pipeline), which would drift as #303, #304, #305 and #314 land, the documentation keeps a single generic Developers page: overview, the guiding principle (everything that can be computed is generated or checked, never maintained by hand), and links to READMEs placed in the directories they describe.

    README Content
    ext/README.md (main one: the plan) one extension per modeling; availability = file presence (#303); :draft → :valid; add a problem; add a modeling (entry in the modeling table + documentation adapter); table "I want to do X → read Y"
    ext/<Modeling>/README.md template of a problem in this modeling, what it must return
    ext/MetaData/README.md metadata format, status, reference_objective
    ext/Descriptions/README.md format of a description
    test/README.md environments, labels run ci … / test …, how to add a test (#304)
    .github/workflows/README.md crons, reports, automatic issues (#305)
    results pipeline README (location chosen in #314) how results are computed and published

    Rules:

    Changes to the structure table above: the Developers row becomes "one generic page, linking to the READMEs"; the 'Done when' item "Structure above" is read accordingly.

  7. ocots commented on Nov 6, 2026

    @ocots
    MemberAuthor

    Update after #360 and #375

    Principle since #360: three kinds of tests. Does not break (every CI run, short) and model equivalence (every CI run, no solve) can fail; the convergence report (cron, or label test convergence) gives the solver status and the relative gap of the objective to the reference objective (#375), never fails, no tolerance. The description is updated:

    • Problem page, results: solver status and gap to the reference per configuration; no ✓/✗ on convergence and no tolerance; ✓/✗ only for what is tested (does not break, model equivalence).
    • Problem page, comparison: NLP equivalence status ([Paper] JuMP models for Euler, trapeze and midpoint, and NLP equivalence tests #284), not gaps between the objectives of two modelings (two optimization paths, not two models).
    • Status page: statuses, and the latest convergence report of the cron (gap, change since the previous run). It replaces "pass/fail per configuration, known failures" of the comment of 2026-11-04: :known_failures is dropped ([Metadata] Computed features, reference objective, shared initial guess #306).
    • User guide: "Compare modelings (same NLP, same solution)" becomes same NLP only.
    • Developers: Tests and CI describe the three kinds of tests.
    • READMEs (comment of 2026-11-04): the reference objectives are documented in tools/references/README.md ([Metadata] Reference objectives per scheme, computed by a script #375), the tests in test/README.md; ext/MetaData/README.md covers the metadata format and statuses and links to them.

    🤖 Generated with Claude Code

  8. ocots commented on Nov 7, 2026

    @ocots
    MemberAuthor

    Taken by an agent; draft PR to follow. A plan is proposed to the maintainer before any code.

  9. ocots commented on Nov 7, 2026

    @ocots
    MemberAuthor

    Written by Claude (Claude Code) at the request of ocots.

    Draft PR #408. Choices made there, to review:

    🤖 Generated with Claude Code

  10. ocots commented on Nov 8, 2026

    @ocots
    MemberAuthor

    Done: every item of "Done when" is checked and verified on main.

    • VitePress structure in place: Getting started (Installation, Your first problem, Guided tour), User guide, Problems (overview + generated pages + gallery + status), Developers, API Reference, Migrating from 0.5; the old tutorial-*.md pages are gone.
    • The Installation page explains the extension mechanism and generates the "what to install for what" table from modelings().
    • Problem pages are generated with conditional sections and one tab per modeling.
    • The guide pages run short code with hidden checks (@assert … # hide).
    • The Status page is public and linked from the overview/gallery and the Developers page.
    • [Doc] review of examples published on the website #229 and [Doc] Intial guess #151 are closed.

    One divergence from the specification, intentional: visualize/visualize.svg are obsolete since #134 was closed not planned — solutions are drawn in the browser (ProblemPlot.vue) from the trajectories the convergence crons publish.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions