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

未关闭
  • 哪里不对？
#307 5 条评论 0 个 reaction 已指派 1 人 在 GitHub 查看

维护者通常 1 天内回复

@ocots 已经在做这个了。

开始于 2026年11月4日。

评估

这个 Issue 还没有评估数据。

描述

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.
主要语言
Julia
星标
13
派生
1
平均合并
3 小时 20 分钟
30 天内合并 PR
27

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

control-toolbox/OptimalControlProblems.jl 的其他 Issue

查看 control-toolbox/OptimalControlProblems.jl 的全部 Issue

相似的 Issue

更多 Julia Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。