Skip to content

[Doc] Migrate the documentation to DocumenterVitepress #311

Closed

Description

@ocots

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

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

Activity

  1. ocots commented on Nov 4, 2026

    @ocots
    MemberAuthor

    Addition: the gallery of problems of #314 (Vue component, filters, cards with SVG thumbnails) and the results copied into docs/src/public/results/ are part of the VitePress site; plan them in the migration.

  2. ocots commented on Nov 5, 2026

    @ocots
    MemberAuthor

    From #304 (PRs #319, #324): test/README.md now documents the tests (layout, how to run, statuses and reports, labels, how to add a test or an environment), procedures only. The docs can link to it rather than duplicate it. In docs/make.jl, apply SITE18 (push LOAD_PATH, never pushfirst!), as the CTX packages now do.

  3. ocots commented on Nov 5, 2026

    @ocots
    MemberAuthor

    Taken by an agent; draft PR to follow.

  4. ocots commented on Nov 5, 2026

    @ocots
    MemberAuthor

    The VitePress migration is in progress. The legacy interactive problems browser currently contains inline HTML/JavaScript that VitePress treats as Vue template and rejects during the build. Following the issue specification, I am deferring the browser to #314 (gallery) for a dedicated Vue/component migration; the VitePress site now documents this deferral and builds without the browser page.

  5. ocots commented on Nov 5, 2026

    @ocots
    MemberAuthor

    Update: after discussing the direction, the browser is not being deferred to #314. The legacy inline HTML/DataTables implementation has been replaced in PR #382 by a new Vue component with native search, sorting, filters, constraint chips, row details, and CSV export. The old browser implementation is removed rather than carried forward.

  6. ocots commented on Nov 7, 2026

    @ocots
    MemberAuthor

    Written by Claude (Claude Code) at the request of ocots.

    Closing: the migration is done by #382

    Checked against main (c3ade68) and the SITE rules of ct-conventions v0.10.0.

    Delivered by PR #382:

    • Build with DocumenterVitepress.MarkdownVitepress; the generated problem pages (docs/problems.jl) work under VitePress.
    • The problems browser is a new Vue component (docs/src/components/ProblemsBrowser.vue: search, sorting, filters, constraint chips, row details, CSV export). It reads JSON generated by docs/browser.jl; the old HTML/DataTables code is removed.
    • Manifest.toml and Project.toml are also copied to docs/src/public/assets/, so VitePress serves them.
    • Deployment (SITE13): stable tags and main (dev), deploydocs guarded by bases.txt, previews on documentation push preview, DocPreviewCleanup.yml present.
    • npm versions pinned (SITE14).
    • Mermaid: the site has no diagrams, so nothing to check.

    Moved elsewhere:

    #307 and #314 no longer wait for this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions