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

Đang mở
  • Có gì không ổn?
#307 5 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@ocots đang làm issue này rồi.

Từ ngày 4/11/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

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.
Ngôn ngữ chính
Julia
Star
13
Fork
1
Merge trung bình
3 giờ 20 phút
Pull request đã merge (30 ngày)
27

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của control-toolbox/OptimalControlProblems.jl

Tất cả issue của control-toolbox/OptimalControlProblems.jl

Issue tương tự

Thêm issue về Julia

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.