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

Aberta
  • Algo errado?
#307 5 comentários 0 reações 1 responsável Ver no GitHub

Mantenedores costumam responder em até 1 dia

@ocots já está trabalhando nisso.

Desde 4/11/2026.

Avaliação

Esta issue ainda não foi avaliada.

Descrição

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.

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, same solution); Plot and visualize (plot(sol), plot!, visualize, #175, #134)
Problems Overview (modelings, statuses, metadata, reference objective and its source, references); Gallery (#314); Status (public: statuses and latest cron results, #305); 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 (environments, labels run ci … and test …, #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): table per modeling and configuration; reference objective and its source; a visible table of checks (objective within the tolerance of the reference, consistency between modelings, convergence), each ✓ or ✗. The build never fails on them: tests and crons are where failures fail.
  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, objective gaps.
  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.
Linguagem predominante
Julia
Estrelas
13
Forks
1
Merge médio
3h 20min
PRs com merge (30d)
27

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de control-toolbox/OptimalControlProblems.jl

Todas as issues de control-toolbox/OptimalControlProblems.jl

Issues semelhantes

Mais issues de Julia

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.