[Doc] Results pipeline for the documentation, and a gallery of problems

Đang mở
  • Có gì không ổn?
#314 4 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

Separate the computations shown in the documentation (solving every problem, plots), which are long and may fail, from the documentation build, which must be fast and never fail because of a problem. Jobs compute results and store them; the documentation only reads what exists; each problem page shows the results if they exist and are up to date, says so otherwise. Problem pages are reached through a gallery instead of a list in the sidebar.

Part of #307. Related: #305 (crons write their reports to the same branch), #306 (features for the gallery filters), #134 (visualize), #311 (VitePress).

Storage: a results branch

  • An orphan branch results, rewritten with a single commit on each update so that it does not grow. Not a tracked directory in main (regenerated SVGs would bloat the history).
  • Shared with the crons of #305 (no separate cron-reports branch).
  • Locally: a git-ignored directory (e.g. docs/results/) filled by a script, so the documentation also builds offline and in previews.
results/                         # branch `results`
├── manifest.json                # date, commit, list of runs
├── env/<run id>/                # environment of each computation run
│   ├── Project.toml, Manifest.toml
│   ├── versioninfo.txt          # output of versioninfo()
│   └── status.txt, status-manifest.txt   # Pkg.status(), Pkg.status(mode=PKGMODE_MANIFEST)
├── problems/<problem>/
│   ├── result.json              # per modeling and configuration: objective, iterations, times, status; fingerprint; run id
│   ├── state.svg, control.svg, costate.svg
│   ├── visualize.svg            # if the problem has a visualisation (#134)
│   └── thumbnail.svg            # for the gallery
└── cron/                        # reports of the crons (#305)

Robustness

  • One writer. Computation jobs run in parallel, one per problem, and only upload workflow artifacts; a final job collects them and makes the single commit. No concurrent writes; a failing problem does not prevent the others from being published.

  • Freshness. Each result.json records a fingerprint: a hash of the problem files (metadata, model files of every modeling, description) and the versions of the packages used. At build time the documentation recomputes the fingerprint and shows, per problem:

    • up to date: the results;
    • stale: the results, marked "computed for commit X";
    • missing: "results not computed yet".

    The build never fails on missing or stale results.

  • Triggers of the computations: a push to main that changes a problem (only problems whose fingerprint changed), weekly (with the crons of #305, staggered), workflow_dispatch (all problems or a list). The documentation workflow never triggers or waits for them.

  • VitePress: copy the results into docs/src/public/results/ before makedocs (VitePress silently drops files it does not recognise outside public/, see the notes on the VitePress backend in ct-conventions rules/site.md).

Problem pages

Generated, never hand-written (docs/problems.jl today):

  • description (ext/Descriptions/<p>.md), parameters, features (#306), status per modeling (#303), references;
  • how to get and solve it in each modeling where it exists (short code, not executed beyond trivial calls);
  • results from result.json, with the freshness badge; plots as SVG (rule SITE12), visualize.svg when it exists;
  • Reproducibility block, same presentation as the OptimalControl.jl documentation (docs/src/index.md, section "Reproducibility"): a table to download Project.toml and Manifest.toml of the run that produced the results, and a collapsible ::: details block with versioninfo, Pkg.status() and the full dependency tree, read from env/<run id>/ (they cannot be executed at build time, since the results come from another environment).

No heavy computation at documentation build time: the only code executed by the build is short (tutorials, trivial calls).

Gallery

Replaces the list of problems in the sidebar, since the collection will grow quickly:

  • one card per problem: thumbnail (thumbnail.svg, or the visualisation), name, modelings and statuses, tags;
  • filters by modeling, status, tag and features (dimensions, free final time, constraints);
  • a Vue component (see docs/src/components/ in CTBase.jl), with the existing interactive table (docs/browser.jl) as a second view of the same page, or replaced by it.

Done when

  • Workflow computing results per problem in parallel, single collector, branch results rewritten with one commit; env/<run id>/ saved for each run.
  • Fingerprint computed identically by the jobs and by the documentation build; up to date / stale / missing shown on the pages, shown on purpose for each case.
  • Local script filling docs/results/; documentation builds with no results at all.
  • Problem pages generated with results, plots, visualisation and Reproducibility block.
  • Gallery page with filters; problems removed from the sidebar list.
  • Documentation build time reported before and after.
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.