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

Ouverte
  • Quelque chose ne va pas ?
#307 6 commentaires 0 réactions 1 personne assignée Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

@ocots y travaille déjà.

Depuis le 4/11/2026.

Évaluation

Cette issue n'a pas encore été évaluée.

Description

documentation

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 (#314).
  2. Description and mathematical formulation (ext/Descriptions/<p>.md).
  3. Parameters and features (#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, #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 (#375), with how the reference was computed. No ✓ or ✗ on convergence and no tolerance (#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 (#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 (#314).

Executed code

  • No heavy computation at build time: solves come from the results branch (#314).
  • User guide pages execute short code, with hidden checks (@assert … # hide) as in OptimalControl.jl.

Also closes

  • #229: wrong first-line comment, formatting of named tuples, plot labels (solved by plot!(sol)), a note on the MKL warning on macOS ARM (upstream), stale CT* versions (gone with #283).
  • #151: Initial guess page.

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.
  • #229 and #151 closed.
Langage dominant
Julia
Étoiles
13
Forks
1
Merge moyen
3 h 24 min
PR mergées (30 j)
34

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de control-toolbox/OptimalControlProblems.jl

Toutes les issues de control-toolbox/OptimalControlProblems.jl

Issues similaires

Plus d'issues Julia

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.