[Doc] Migrate the documentation to DocumenterVitepress

Offen
  • Stimmt etwas nicht?
#311 4 Kommentare 0 Reaktionen 1 zugewiesene Person Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@ocots arbeitet bereits daran.

Seit 04.11.2026.

Bewertung

Dieses Issue wurde noch nicht bewertet.

Beschreibung

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).

Vorherrschende Sprache
Julia
Sterne
13
Forks
1
Ø Merge
3 Std. 20 Min.
Gemergte PRs (30 T.)
27

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus control-toolbox/OptimalControlProblems.jl

Alle Issues in control-toolbox/OptimalControlProblems.jl

Ähnliche Issues

Weitere Issues zu Julia

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.