Repository navigation
comline doc: every version, per-format paths, a cache, [doc] formats/versions - #119
Merged
Merged
Conversation
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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The CLI half of ComlineProject/generation#101 (generation#102).
comline_core::doc::changelog, which uses the same rules ascomline diff.<out>/<format>/<version>/, withunreleased/for the working tree. Then the renderer's site index goes at<out>/<format>/:index.html,versions.jsandcompare.htmlfor HTML, andindex.mdfor Markdown.jsonwrites<version>/model.jsonplusindex.json.<out>/<format>/.comline-doc.jsonkeys 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 andlinks. 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).--versionrenders one version alone into its folder, and--changelog-fromapplies only there; without--versionit warns.--formatis repeatable or comma-separated, and[doc] formatbecomesformats.docstree 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.gitignoreaddsdocs/api/html/.docs/cli.mdis 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 inunreleased/, 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-markdownandcomline-doc-htmlat generation6889d3d; comline-rust0e39319(comline-rust#90); comline-typescriptad87568(comline-typescript#109). Core is unchanged at5259393.Generated code is byte-identical. I ran
comline generatewith main's binary and with this branch's onsimple_project,chat_projectandvalidated_project. Each project declared Rust and TypeScript, and I also ran--target rust --mode lib.diff -rfound 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()andManifest::reuses()are unit-tested ina_changed_renderer_invalidates_every_folder.