[Doc] Migrate the documentation to DocumenterVitepress

Fechada
  • Algo errado?
#311 5 comentários 0 reações 1 responsável Ver no GitHub

Mantenedores costumam responder em até 1 dia

@ocots já está trabalhando nisso.

Desde 4/11/2026.

Avaliação

Esta issue ainda não foi avaliada.

Descrição

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

Linguagem predominante
Julia
Estrelas
13
Forks
1
Merge médio
3h 36min
PRs com merge (30d)
57

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de control-toolbox/OptimalControlProblems.jl

Todas as issues de control-toolbox/OptimalControlProblems.jl

Issues semelhantes

Mais issues de Julia

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.