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

Abierto
  • ¿Algo no está bien?
#314 4 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@ocots ya está trabajando en esto.

Desde el 4/11/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

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.
Lenguaje dominante
Julia
Estrellas
13
Forks
1
Merge medio
3 h 20 min
PR fusionados (30 d)
27

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de control-toolbox/OptimalControlProblems.jl

Todos los issues de control-toolbox/OptimalControlProblems.jl

Issues similares

Más issues de Julia

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.