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

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); results now come from the convergence cron. Where an older comment contradicts this description, the description wins; what changed is listed in the update comment.

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.

One source of results: the convergence cron (decision of 2026-11-06). Since #360 and #375, the weekly cron of each scope already solves every problem, in every modeling and configuration, on its default grid, and publishes the results on the results branch (*-results.tsv: solver status, objective, iterations, time, gap to the reference). The documentation results come from these runs, not from a second computation: the cron jobs also write result.json, the plots and the environment of the run (below). No separate computation workflow to keep in sync with the tests.

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

• The orphan branch results (exists since #305: cron/ with the reports and state.json; protected against deletion by the ruleset protect-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).
• Written only by the publish job of the crons (.github/workflows/cron-reusable.yml, concurrency group cron-results).
• 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: solver status, objective, iterations, time, gap to the reference; 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. The test jobs of the crons run in parallel (per scope and platform) and only upload workflow artifacts; the publish job collects them and makes the single commit (as today for the reports). No concurrent writes; a failing problem does not prevent the others from being published. Plots need Plots in the cron environments (or a step after the solves): to decide when taking the issue.

• 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: those of the crons (weekly per scope, workflow_dispatch); to add if needed: a push to main that changes a problem (only problems whose fingerprint changed), through the same cron workflows with problem=…. 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: solver status and gap to the reference per configuration, no ✓ or ✗ on convergence (#360, #307); 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

• The cron workflows write result.json, the plots and env/<run id>/ for each run, through the existing publish job; branch results rewritten with one commit.
• 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.