Skip to content

comline doc: every version, per-format paths, a cache, [doc] formats/versions - #119

Merged
Kinflou merged 5 commits into
mainfrom
doc/multi-version
Nov 1, 2026
Merged

Kinflou merged 5 commits into
mainfrom
doc/multi-version

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

The CLI half of ComlineProject/generation#101 (generation#102).

  • Every version by default. Every release and dev build in the CAS chain, then the unreleased working state when its frozen schemas or headers differ from the last build. Each version's model carries the changelog from the version before it in the list, computed with comline_core::doc::changelog, which uses the same rules as comline diff.
  • Paths. Output goes to <out>/<format>/<version>/, with unreleased/ for the working tree. Then the renderer's site index goes at <out>/<format>/: index.html, versions.js and compare.html for HTML, and index.md for Markdown. json writes <version>/model.json plus index.json.
  • Caching. <out>/<format>/.comline-doc.json keys each version folder by its commit, the previous version's commit, the renderer id and version (plus the CLI version for built-ins, or the file's blake3 hash for [doc] renderer), the model version and links. A folder whose key matches is kept. The unreleased state always re-renders, and folders of versions no longer listed are removed.
  • [doc] versions ("all", { last = N }, { since = "v" }, { releases_only = true }, which combine). --version renders one version alone into its folder, and --changelog-from applies only there; without --version it warns.
  • --format is repeatable or comma-separated, and [doc] format becomes formats.
  • Notes for old versions. A version without a docs tree entry (from before core#152) says it has no headers. A version whose protocols have no wire summary (core#153) says so.
  • comline new's .gitignore adds docs/api/html/.
  • docs/cli.md is updated.

Tests: the existing doc tests are moved to the new paths. New tests:

  • every_version_is_documented_and_a_second_run_rerenders_only_unreleased: a marker survives in a kept folder and is wiped in unreleased/, and the second run reports "1 rendered, 5 unchanged".
  • doc_versions_trims_the_list.
  • html_writes_a_self_contained_site_per_version.

The external-renderer equivalence tests drop the manifests, which name their renderer, before comparing.

Pins: comline-codegen, comline-doc-markdown and comline-doc-html at generation 6889d3d; comline-rust 0e39319 (comline-rust#90); comline-typescript ad87568 (comline-typescript#109). Core is unchanged at 5259393.

Generated code is byte-identical. I ran comline generate with main's binary and with this branch's on simple_project, chat_project and validated_project. Each project declared Rust and TypeScript, and I also ran --target rust --mode lib. diff -r found no differences.

Cache key and renderer changes. A built-in renderer's key uses its content-hashed version (generation 6889d3d), so a CLI with a changed renderer re-renders every folder. cache_key() and Manifest::reuses() are unit-tested in a_changed_renderer_invalidates_every_folder.

Kinflou added 2 commits November 1, 2026 21:41
…ions

comline doc now documents every release, dev build and the unreleased
working state (when it differs from the last build), each into
<out>/<format>/<version>/ with the changelog from the version before it,
then asks the renderer for the site's index: index.html, the version
picker's versions.js and compare.html for HTML, index.md for Markdown,
index.json for json.

A built version's folder is cached by its commit, the previous version's
commit, the renderer and its version, the model version and the links, in
<out>/<format>/.comline-doc.json; a second run re-renders only the
unreleased state and new versions. [doc] versions trims the list (all,
last, since, releases_only); --version documents one version alone.
Old versions carry notes for what they lack (headers before core#152,
wire tables until core#153).

--format is repeatable and comma-separated; [doc] format is now formats.
comline new gitignores docs/api/html/.

Pins comline-codegen and the doc renderers at generation 5eb12c0,
comline-rust b999d67 and comline-typescript 355b67c.
Kinflou added 3 commits November 1, 2026 21:46
The external-renderer tests build the official renderers from
tests/fixtures/generators; they must render what the built-ins do.
Pins generation 6889d3d, whose official renderers report
<crate version>+<content hash> as their version, so a changed built-in
renderer invalidates every cached folder. The key is now cache_key(),
and Manifest::reuses() decides; a unit test covers both. Also pins
comline-rust 0e39319 and comline-typescript ad87568.
@Kinflou
Kinflou merged commit 45d4343 into main Nov 1, 2026
2 checks passed
@Kinflou
Kinflou deleted the doc/multi-version branch November 1, 2026 14:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant