[Doc] Migrate the documentation to DocumenterVitepress

Abierto
  • ¿Algo no está bien?
#311 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

Move the documentation from Documenter's classic HTML backend to DocumenterVitepress, the current standard of the ecosystem (as in CTBase.jl, CTModels.jl, …), and bring the site in line with the SITE rules of ct-conventions.

References

  • Rules: rules/site.md in ct-conventions (pinned version in AGENTS.md, see #309).
  • Migration recipe: recipes/vitepress-migration.md in ct-agents.
  • Examples: docs/ of CTBase.jl and CTModels.jl (DocumenterVitepress 0.3.5, docs/package.json, docs/src/components/).

Points specific to this package

  • Generated pages: docs/problems.jl (one page per problem) and docs/browser.jl (interactive problems browser, raw HTML/CSS/JS) must work under VitePress. The browser is the main risk: raw HTML and scripts behave differently, a Vue component (as in docs/src/components/ of CTBase) may be needed.
  • Plots rendered as SVG (SITE12); they appear in every problem page.
  • Downloadable assets: make.jl copies Manifest.toml and Project.toml to docs/src/assets/. VitePress silently drops such files from the build: serve them from docs/src/public/ as well (see the notes on the VitePress backend in rules/site.md).
  • Mermaid: the site uses DocumenterMermaid; check how diagrams render under VitePress.
  • API reference generated with with_api_reference (SITE1, SITE2, SITE10), extensions documented when present (SITE3), InterLinks with local fallback inventories (SITE4).
  • Deployment on stable tags only, previews on request (SITE13): this changes .github/workflows/Documentation.yml. Pin the npm dependencies (SITE14).

Order

After the port to v2 (#283), which keeps the current pages building: a mechanical migration of the existing content to DocumenterVitepress, without rewriting it. The rewrite (#307) then happens directly in the VitePress structure, and the results pipeline and gallery (#314) in parallel. If the browser turns out hard to port, migrate it in its own PR, or leave it to #314 (gallery).

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.