From 7855d80f867ce5689a39c581c340676365b79e8b Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 1 Nov 2026 21:45:04 +0800 Subject: [PATCH 1/2] docs: comline doc documents every version, with a picker and comparisons The documenting guide, the comline doc reference and the comline.toml reference cover per-format, per-version paths, the cache, [doc] formats and versions, the HTML version picker and comparison page, and Markdown versioning through site tooling such as mike. The generator protocol page documents RenderOptions' version, versions and notes, the Description's sites and version, and the doc model's additive version rule (core#158). Both schema copies are synced, and the std sync script reads the new layout as well as the old. --- docs/docs/guide/documenting.md | 108 ++++++++--- docs/docs/reference/cli.md | 2 +- .../reference/congregation/comline-toml.md | 10 +- docs/docs/reference/generator-protocol.md | 26 ++- docs/docs/reference/tools/doc.md | 130 +++++++++++-- docs/docs/schemas/comline-toml/0.x.json | 80 +++++++- docs/docs/schemas/doc-model/1.json | 182 +++++++++++++++++- scripts/sync-std-docs.py | 5 + 8 files changed, 484 insertions(+), 59 deletions(-) diff --git a/docs/docs/guide/documenting.md b/docs/docs/guide/documenting.md index 6a64827..6b93f12 100644 --- a/docs/docs/guide/documenting.md +++ b/docs/docs/guide/documenting.md @@ -43,28 +43,53 @@ next to each name. comline doc ``` -This compiles the working tree and writes Markdown into `docs/api/`: +This documents every version of the package: each release, each dev build, +and the working tree's unreleased changes. Each one is written as Markdown into +its own folder under `docs/api/markdown/`: + +```text +docs/api/markdown/ +├── index.md # the versions, grouped by release +├── 0.1.0/ +├── 0.2.0-dev.1/ # a dev build, listed under the release it leads to +├── 0.2.0/ +└── unreleased/ # the working tree, when it differs from the last build +``` + +Before the first `comline build`, `unreleased/` is the only version. Each +version's folder has these pages: | File | What's on it | |---|---| | `index.md` | The package's name and version, its `config.idp` header, and a table of its modules. | | `.md` | One per schema (`types::user` is `types/user.md`): its header, a table of what it declares, then each declaration with its docs, annotations, fields, arguments, variants, and each protocol's wire summary, the same table the editor's hover and `comline inspect` show. | -| `changelog.md` | With `--changelog-from`: what changed, as `comline diff` reports it. | +| `changelog.md` | What changed since the version before it, as `comline diff` reports it. | | `nav.yml` | The pages as a `nav` list for mkdocs or zensical. | Every declaration has an anchor, its name in lowercase (`api.md#order`), and a type links to the declaration it names, on the same page or another module's. +Run it again and only what changed is rendered again. A built version never +changes, so its folder is kept: `docs/api/markdown/.comline-doc.json` records +what each folder was rendered from. Usually only `unreleased/` and any new +version are rendered. + ### Put them on a site The pages are plain Markdown, so they drop into an mkdocs or zensical site: -render into the site's `docs/` tree and copy `nav.yml`'s entries into +render into the site's `docs/` tree and copy a version's `nav.yml` entries into `mkdocs.yml`. ```bash comline doc --out site/docs/api ``` +The Markdown output has no version picker. To publish several versions, use +your site tool's versioning. With mkdocs, [mike](https://github.com/jimporter/mike) +deploys each version folder as a version of the site and adds a selector. To +publish only the latest version, trim the list with `[doc] versions` (see +[Choose the versions](#3-choose-the-versions)). + ### Or as a site of its own `--format html` writes a finished static site instead, with the same content @@ -74,12 +99,34 @@ as the Markdown pages: comline doc --format html --out site ``` -Open `site/index.html` straight from disk, or put the folder on any static -host. Each page has a sidebar of modules and their declarations and a search -box over every declaration. The theme follows the OS's light or dark setting. -Nothing loads from the network: the stylesheet and the search script (with its -index inlined) are files in the folder, and every link is relative. To make it -the default, set `format = "html"` under `[doc]` in `comline.toml`. +Open `site/html/index.html` straight from disk, or put the folder on any static +host. It opens the latest version: the newest release, or the newest dev build +before the first release. + +- **Each page** has a sidebar of modules and their declarations and a search box + over every declaration. The theme follows the OS's light or dark setting. +- **The version picker** in the header switches versions and keeps your place: + the same page and declaration in the chosen version, or that version's + overview, with a note, when it doesn't have them. Dev builds are grouped under + the release they lead to. +- **Compare** (in the header, or `site/html/compare.html`) shows how versions + differ. Tick two to see what changed between them, grouped by declaration and + labelled major, minor or patch. Tick more to see a grid of every declaration + and member, with its type or signature in each version. The labels are the + same ones `comline diff` gives, computed when the docs are rendered. + +Nothing loads from the network: the stylesheet, the search index and the +version data are files in the folder, and every link is relative. To make HTML +the default, or to write several formats in one run, list them under `[doc]` in +`comline.toml`: + +```toml +[doc] +formats = ["html", "markdown"] +``` + +The site is generated, so a new project's `.gitignore` (from `comline new`) +leaves out `docs/api/html/`. ### Link to dependencies @@ -95,33 +142,47 @@ A type from `billing`'s `api` module, `Invoice`, then links to `https://docs.example.com/billing/api/#invoice`: the base, the module, and the anchor, in the directory-URL form mkdocs and zensical publish pages at. -## 3. Document a release +## 3. Choose the versions + +Every version is documented by default. `[doc] versions` trims the list: -`--version` documents a built version instead of the working tree: a version +```toml +[doc] +versions = { last = 5 } # the newest five +# versions = { since = "0.3.0" } # 0.3.0 and newer +# versions = { releases_only = true } # releases only: no dev builds, no unreleased state +``` + +The keys combine: `{ releases_only = true, last = 3 }` is the last three +releases. A version that's trimmed away has its folder removed on the next run. + +`--version` documents one built version on its own, into its folder: a version string, a commit hash, or `HEAD`. ```bash -comline doc --version 0.2.0 --out site/docs/api/0.2.0 +comline doc --version 0.2.0 ``` -A build stores the `//!` headers with the version, so a version documents with -the headers it was built with, even after the sources change. Two things need -the source and are missing from a built version: protocols have no wire -summary, and dependency types have no link. A version built before headers -were stored has none. - -`--changelog-from` adds what changed since an earlier built version: +`--changelog-from` adds what changed since an earlier built version to it: ```bash comline doc --version 0.2.0 --changelog-from 0.1.0 ``` +A build stores the `//!` headers with the version, so a version documents with +the headers it was built with, even after the sources change. Two things need +the source and are missing from a built version: protocols have no wire +summary, and dependency types have no link. A version built before headers +were stored has no headers. Its pages open with a note saying what's missing. + ## 4. Or take the model -`--format json` writes the documentation model itself, `model.json`: the same +`--format json` writes the documentation model itself, each version's +`model.json`, with `docs/api/json/index.json` listing the versions: the same data the pages are rendered from, as JSON. Its shape is a published schema, [`doc-model/1.json`](../schemas/doc-model/1.json), so a tool of your own can -render it any way it likes. +render it any way it likes. The schema grows without a version bump when +something is added, so skip any `kind` you don't know. ```bash comline doc --format json @@ -141,8 +202,9 @@ and the flag wins: | Key | Flag | Default | |---|---|---| | `out` | `--out` | `docs/api` | -| `format` | `--format` | `markdown` | -| `changelog_from` | `--changelog-from` | none | +| `formats` | `--format` | `["markdown"]` | +| `versions` | `--version` (one version) | `"all"` | +| `changelog_from` | `--changelog-from` | none; with `--version` only | | `renderer`, `timeout` | none | the built-in renderer | | `links` | none | none | diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index ac746b5..7052989 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -40,7 +40,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate | `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--validate-on-decode ] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. A target can use an [external generator](../guide/extending/generators.md) (`generator = ""`) and map [encodings](../guide/extending/encodings.md#5-map-it-to-a-type). | | `comline release [1.0] [--raise --reason ] [--yes]` | Build, then release: create the version from the highest bump since the last release ([builds and releases](versioning.md#builds-and-releases)). `--raise patch\|minor\|major` goes higher, with a `--reason` recorded with the release; it never lowers. `1.0` makes a `0.x` package stable after showing what that commits to (its protocols, and what's worth settling first). Raising to major and `1.0` ask on a terminal; without one they refuse (exit `2`) unless `--yes` (`-y`). | | `comline diff []` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`` default). | -| `comline doc [--out ] [--version ] [--changelog-from ] [--format ]` | Write the package's documentation: Markdown pages (an index, one page per module with its `//!` header, every declaration's `///` docs and each protocol's wire summary, a changelog, an mkdocs/zensical `nav.yml`), `--format html` for a self-contained static site with the same content and a search box, or `--format json` for the documentation model. The working tree by default; `--version` documents a built version from its frozen IR and headers. Defaults from [`comline.toml`](congregation/comline-toml.md#doc)'s `[doc]`. No `.comline/` write. See [comline doc](tools/doc.md). | +| `comline doc [--out ] [--version ] [--changelog-from ] [--format ]` | Write the package's documentation for every version (each release, dev build and the unreleased working state), each into `///` with the changelog from the version before it: Markdown pages (an index, one page per module with its `//!` header, every declaration's `///` docs and each protocol's wire summary, a changelog, an mkdocs/zensical `nav.yml`), `--format html` for a self-contained static site with the same content, a search box, a version picker and a page comparing versions, or `--format json` for the documentation model. Built versions are cached, so a run re-renders only the unreleased state and new versions; `--version` documents one built version. Defaults from [`comline.toml`](congregation/comline-toml.md#doc)'s `[doc]`. No `.comline/` write. See [comline doc](tools/doc.md). | | `comline conformance --impl [--encoding ]... [--corpus ] [--timeout ]` | Run an implementation of an encoding against its vectors. The package's declared [`encodings`](../guide/extending/encodings.md) ship vectors beside their profiles (`profiles/x.vectors.json`); `--impl` is a process speaking the [ops protocol](conformance.md#the-ops-protocol), run once with a cleared environment, a time limit (`--timeout`, 60 s) and a capped stdout. `--encoding` limits the run to one encoding (repeatable); `--corpus` runs a corpus laid out like the runtime's `runtime/conformance` instead, which is how the official encodings are proven. A failed or unimplemented case, or an unproven profile fact, exits `1`. See [Formats and framings](../guide/extending/encodings.md#3-write-vectors-and-prove-an-implementation). | | `comline clean [--dry-run]` | Remove generated code (the `generate` output root or files). Never touches `.comline/`. | | `comline reset [--force] [--dry-run]` | **Destructive.** Delete `.comline/` — the whole version history, no undo — *and* generated code. Next `build` starts over at `0.0.1`. On a terminal it shows how many versions will be lost and makes you type `reset`; without a terminal it refuses (exit `2`) unless `--force`. | diff --git a/docs/docs/reference/congregation/comline-toml.md b/docs/docs/reference/congregation/comline-toml.md index 8a81e4f..afd7f85 100644 --- a/docs/docs/reference/congregation/comline-toml.md +++ b/docs/docs/reference/congregation/comline-toml.md @@ -207,17 +207,19 @@ Settings for [`comline doc`](../tools/doc.md). Each key but `renderer`, | Key | Type | Default | Meaning | |---|---|---|---| | `out` | string (path) | `"docs/api"` | Output directory, relative to `comline.toml`. `--out` overrides it. | -| `format` | string | `"markdown"` | `markdown` (pages), `html` (a static site), `json` (the documentation model, `model.json`), or another renderer id `renderer` offers. `--format` overrides it. | -| `renderer` | string (path) | — | A renderer outside `comline`: a `.wasm` (run sandboxed under wasmtime) or an executable, relative to `comline.toml`'s directory. Run exactly like an external [`generator`](#generator). Unset, the built-in renderer for `format` is used. | +| `formats` | array of strings | `["markdown"]` | What to write, each into `//` in one run: `markdown` (pages), `html` (a static site), `json` (the documentation model, `model.json`), or another renderer id `renderer` offers. `--format` overrides it. Replaces `format`, which is no longer accepted. | +| `versions` | `"all"` or table | `"all"` | Which versions to document. `"all"`: every release, every dev build and the unreleased working state. A table trims the list, and its keys combine, applied in this order: `releases_only = true` keeps releases alone (no dev builds, no unreleased state), `since = "0.3.0"` keeps that version and newer, `last = N` keeps the newest N (the unreleased state counts as one). `--version` documents one version instead. | +| `renderer` | string (path) | — | A renderer outside `comline`: a `.wasm` (run sandboxed under wasmtime) or an executable, relative to `comline.toml`'s directory. Run exactly like an external [`generator`](#generator). Unset, the built-in renderer for each format is used. | | `timeout` | integer (seconds, ≥ 1) | `60` | The wall-time limit for each call to `renderer`. | | `links` | table | — | Where each dependency's docs live, by the name the package gives it (or `std`): a base URL. A type from a dependency listed here links to `//#`; one that isn't is plain text. | -| `changelog_from` | string | — | Add a changelog from this built version (a version or commit hash) to the documented one. `--changelog-from` overrides it. | +| `changelog_from` | string | — | With `--version`: add a changelog from this built version (a version or commit hash) to the documented one. `--changelog-from` overrides it. Every version already carries the changelog from the one before it, so a run without `--version` ignores it, with a warning. | ```toml [doc] out = "site/docs/api" +formats = ["html", "markdown"] +versions = { since = "0.3.0", last = 10 } links = { std = "https://example.com/std" } -changelog_from = "0.1.0" ``` ## Layout variables diff --git a/docs/docs/reference/generator-protocol.md b/docs/docs/reference/generator-protocol.md index 691f0a0..5e008d9 100644 --- a/docs/docs/reference/generator-protocol.md +++ b/docs/docs/reference/generator-protocol.md @@ -87,11 +87,33 @@ to a program whose `Description` lists the renderer at the model version. A | `renderer` | string | the renderer's id, from `Description.renderers`: `markdown` | | `model_version` | integer | the documentation model's version (`DOC_MODEL_VERSION`, `1`), readable without parsing `model` | | `model` | string | the documentation model as JSON text, in the shape of [`doc-model/1.json`](../schemas/doc-model/1.json) | -| `options` | `{ links }` | `links`: a dependency's name (or `std`) to the base URL of its docs | +| `options` | `{ links, version, versions, notes }` | see below | + +| Option | Meaning | +|---|---| +| `links` | a dependency's name (or `std`) to the base URL of its docs | +| `version` | set when this render is one version of a multi-version site: the version's folder (`0.2.0`, `0.3.0-dev.2`, `unreleased`). The files land in `//`, so the site's shared files are at `../`. Absent for a site of its own. | +| `versions` | set for a site's index render: every version, oldest first, each `{ id, release, kind, model }`. `release` is the release a dev build leads to (`0.3.0` for `0.3.0-dev.2`), itself for a release, `unreleased` for the working tree; `kind` is `release`, `dev` or `unreleased`; `model` is that version's model as JSON, with its `changelog` from the version before it in the list. The files land at the site's root, and the request's own `model` is the newest version's. | +| `notes` | plain-text notes for every page of this version: what an old version's documentation lacks | A renderer accepts every option and ignores the ones it has no use for. The answer is `Render(Generated)`: files, checked like a generator's. +**Several versions.** [`comline doc`](tools/doc.md) documents every version +with one `Render` per version (with `version` set), then one for the site's +index (with `versions` set). A per-version request carries one model, like a +single-version one, so a renderer that ignores `version` still works: it +renders each version on its own. The index request goes only to a renderer +whose `Description` entry sets `sites`. Both options are additive, so the +protocol version stays `0`. + +**The model's version.** The documentation model follows the same rule as the +protocol: an additive change keeps `model_version` (a new unit, type or change +kind, or a new field that may be absent), so a renderer skips a `kind` it +doesn't know and ignores unknown fields. A consumer validating strictly against +`doc-model/1.json` should expect the schema to grow. Only an incompatible +change bumps the version. + ## Response | Variant | Carries | @@ -108,7 +130,7 @@ answer is `Render(Generated)`: files, checked like a generator's. | `languages` | one entry per generator; a language with several floors has several | | `protocols` | `(min, max)` protocol versions it accepts, inclusive | | `ir_formats` | the IR formats it accepts | -| `renderers` | the documentation renderers it offers, each `{ id, model_versions }`; empty, or absent from an older program, when it offers none | +| `renderers` | the documentation renderers it offers, each `{ id, model_versions, version, sites }`; empty, or absent from an older program, when it offers none. `version` is the renderer's own version, part of `comline doc`'s cache key (empty when absent); `sites` says it renders a multi-version site's index (`false` when absent) | A language entry holds: diff --git a/docs/docs/reference/tools/doc.md b/docs/docs/reference/tools/doc.md index 44d517c..1015886 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -1,27 +1,78 @@ # comline doc ``` -comline doc [--out ] [--version ] [--changelog-from ] [--format markdown|html|json] +comline doc [--out ] [--version ] [--changelog-from ] [--format [,...]] ``` -`comline doc` writes a package's documentation. Like `comline check`, it writes -nothing to `.comline/`. For a walkthrough, see -[Documenting your schemas](../../guide/documenting.md). +`comline doc` writes a package's documentation for every version: each +release, each dev build, and the unreleased working state when it differs from +the last build. Like `comline check`, it writes nothing to `.comline/`. For a +walkthrough, see [Documenting your schemas](../../guide/documenting.md). ## Flags | Flag | Default | Meaning | |---|---|---| | `--out ` | `[doc] out`, else `docs/api` | Where to write, relative to the project. | -| `--version ` | the working tree | Document a built version: a version string, a commit hash (4+ characters), or `HEAD`. | -| `--changelog-from ` | `[doc] changelog_from` | Add what changed from built version `` to the documented one. | -| `--format ` | `[doc] format`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. | +| `--version ` | every version | Document only this built version, into `///`: a version string, a commit hash (4+ characters), or `HEAD`. | +| `--changelog-from ` | `[doc] changelog_from` | With `--version`: add what changed from built version `` to the documented one. | +| `--format ` | `[doc] formats`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. Repeat it, or separate formats with commas. | + +The `[doc]` keys are in [`comline.toml`](../congregation/comline-toml.md#doc), +including `versions`, which trims the list of versions. + +## Versions and paths + +Each format lands in `//`, with one folder per version: + +```text +docs/api/ +├── html/ +│ ├── index.html # points at the latest version +│ ├── compare.html # compare versions +│ ├── compare.js # each version's structure and changes, inlined +│ ├── versions.js # the version list, for the picker +│ ├── style.css +│ ├── .comline-doc.json # the cache manifest +│ ├── 0.1.0/ # a release +│ ├── 0.2.0-dev.1/ # a dev build +│ ├── 0.2.0/ # the release it led to +│ └── unreleased/ # the working tree's changes since the last build +├── markdown/ +│ ├── index.md # the versions, grouped by release +│ ├── 0.1.0/ ... # each with its own nav.yml +│ └── unreleased/ +└── json/ + ├── index.json # the versions, and where each model is + ├── 0.1.0/model.json ... + └── unreleased/model.json +``` -The `[doc]` keys are in [`comline.toml`](../congregation/comline-toml.md#doc). +- A dev build's folder is its full version (`0.2.0-dev.1`), and it belongs to + the release it leads to (`0.2.0`). +- The working tree appears as `unreleased` only when its schemas or headers + differ from the last build. With nothing built, it is the only version. +- Each version carries the changelog from the version before it in the list, + computed by core with the same rules as `comline diff`. The first version + has none. +- The latest version, which `index.html` points at, is the newest release, + else the newest dev build, else the unreleased state. + +**Caching.** A built version never changes, so its folder is kept between +runs. `//.comline-doc.json` records each folder's key: the +version's commit, the commit of the version before it, the renderer's id and +version (and the `comline` version for a built-in renderer, or the renderer +file's hash for `[doc] renderer`), the model version and `[doc] links`. A +folder whose key still matches is left alone, so a run re-renders only the +unreleased state and new versions. A folder for a version no longer listed +(trimmed by `versions`, or the unreleased state once it's built) is removed. +`--version` writes its one folder and drops it from the manifest, so the next +full run re-renders it. ## Output -`markdown`, rendered by the official renderer built into `comline`: +`markdown`, rendered by the official renderer built into `comline`, in each +version's folder: | File | Contents | |---|---| @@ -30,6 +81,11 @@ The `[doc]` keys are in [`comline.toml`](../congregation/comline-toml.md#doc). | `changelog.md` | With a changelog: breaking changes, additions and other changes. | | `nav.yml` | A `nav` list for mkdocs or zensical. | +`/markdown/index.md` lists the versions, newest first, grouped by release. +There is no version picker: switching versions on a published site is left to +site tooling. With mkdocs, [mike](https://github.com/jimporter/mike) deploys +each version folder as a version of the site and adds a version selector. + Each declaration has an anchor, its name in lowercase; a function has `-`. A type links to its declaration's anchor. A type from a dependency links to `//#` when `[doc] links` gives the @@ -40,7 +96,7 @@ format, framing and handshake with where each came from, then each guarantee, held or given up, with its cause and acceptance. `html`, rendered by the official HTML renderer, also built into `comline`, -writes a self-contained static site with the same content: +writes a self-contained static site per version with the same content: | File | Contents | |---|---| @@ -50,24 +106,61 @@ writes a self-contained static site with the same content: | `style.css` | The theme: fixed, light and dark following the OS setting. | | `search.js` | The search index (each declaration's name, kind, module and first line of docs), inlined as data, and the search box's script. | -Every page has a sidebar of modules and their declarations and a search box. +Every page has a sidebar of modules and their declarations, a search box, and +a version picker in the header: + +- The picker is a native drop-down, newest first, with dev builds grouped under + the release they lead to, and a Go button. Choosing a version with the mouse + goes at once. From the keyboard, the arrow keys move the choice, and Enter or + Go navigates. +- It opens the same page and anchor in the chosen version when that version has + them. Otherwise it opens that version's index, with a note saying what was + missing. +- It is fed by `../versions.js`, so a version's pages don't change when + versions are added, and it works under `file://`. + +At `/html/`, the site's root: + +| File | Contents | +|---|---| +| `index.html` | Redirects to the latest version, and lists every version by release. | +| `compare.html` | Compare versions: tick two or more. | +| `compare.js` | Per version: its structure (each unit's kind, each member's type or signature) and its changes from the version before it, inlined as data, then the page's script. | +| `versions.js` | The version list, each version's pages and anchors, and the picker's script. | +| `style.css` | The same theme. | + +On `compare.html`, two versions show what changed between them, grouped by +unit, each change labelled major, minor or patch, with the step it came from. +More versions show a grid with units and members as rows and the chosen +versions as columns. Each cell is the type or signature, or "absent", and a +unit's badge is the largest change across the range. The labels are never +computed in the browser. Core computes each version's changelog from the one +before it (breaking is major, a feature minor, anything else patch), and the +page only collects the steps after the older version up to the newer one. The +grid's cells are structural only. Doc text is rendered from Markdown to HTML; raw HTML in it is shown as text. Nothing loads from the network and every link is relative, so `index.html` opens straight from disk (the index is inlined because a browser blocks `fetch` under `file://`) or from any static host. There is no `nav.yml`. -`json` writes `model.json`, the documentation model, in the shape of -[`doc-model/1.json`](../../schemas/doc-model/1.json). +`json` writes each version's `model.json`, the documentation model, in the +shape of [`doc-model/1.json`](../../schemas/doc-model/1.json), and +`/json/index.json`: the package, the model version, the latest version, +and each version's `id`, `release`, `kind` and model path. Version 1 of the +model grows additively: new kinds and fields that may be absent keep the +version, so a reader should skip a `kind` it doesn't know and ignore unknown +fields. ## Built versions -With `--version`, the model comes from the version's frozen IR and the `//!` -headers stored with it. A built version keeps no source, so: +A built version's model comes from its frozen IR and the `//!` headers stored +with it. A built version keeps no source, so: - its protocols have no wire summary; - a type from a dependency has no link. -A version built before headers were stored has no headers. +A version built before headers were stored has no headers. Each page of such a +version opens with a note saying what it lacks, in both formats. ## External renderers @@ -77,7 +170,10 @@ external generator: a `.wasm` under wasmtime with no filesystem, environment or network, a native executable with an empty environment, the same time limit (`[doc] timeout`, 60 seconds), output caps and path checks. `comline` asks it to describe itself first and refuses it unless it lists the format, at the -model version this `comline` writes, in its `renderers`. +model version this `comline` writes, in its `renderers`. It renders each +version's folder with one `Render` each. The site's index is asked for only +when its `renderers` entry sets `sites`; one that doesn't gets the version +folders alone. ## Exit codes diff --git a/docs/docs/schemas/comline-toml/0.x.json b/docs/docs/schemas/comline-toml/0.x.json index 6a35e16..fc83a7d 100644 --- a/docs/docs/schemas/comline-toml/0.x.json +++ b/docs/docs/schemas/comline-toml/0.x.json @@ -3,6 +3,13 @@ "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { + "AllVersions": { + "description": "The keyword `\"all\"`.", + "enum": [ + "all" + ], + "type": "string" + }, "Doc": { "additionalProperties": false, "description": "The `[doc]` table: `comline doc`'s settings. Each key has a flag that\noverrides it.", @@ -11,15 +18,22 @@ "description": "Add a changelog from this built version (a version or commit hash) to\nthe documented one. `--changelog-from` overrides it.", "type": "string" }, - "format": { - "default": "markdown", - "description": "What to write: `markdown` (pages, from the official renderer or\n`renderer`), `html` (a static site, from the official HTML renderer or\n`renderer`), `json` (the documentation model itself, `model.json`), or\nanother renderer id `renderer` offers. Default `markdown`. `--format`\noverrides it.", + "formats": { + "default": [ + "markdown" + ], + "description": "What to write, each into `//` in one run: `markdown`\n(pages, from the official renderer or `renderer`), `html` (a static\nsite, from the official HTML renderer or `renderer`), `json` (the\ndocumentation model itself, `model.json`), or another renderer id\n`renderer` offers. Default `[\"markdown\"]`. `--format` overrides it.", "examples": [ - "markdown", - "html", - "json" + [ + "html", + "markdown", + "json" + ] ], - "type": "string" + "items": { + "type": "string" + }, + "type": "array" }, "links": { "additionalProperties": { @@ -43,10 +57,62 @@ "format": "uint64", "minimum": 1, "type": "integer" + }, + "versions": { + "allOf": [ + { + "$ref": "#/definitions/DocVersions" + } + ], + "default": "all", + "description": "Which versions to document. Default `\"all\"`: every release, every\ndev build and the unreleased working state. A table trims the list:\n`{ last = 5 }` keeps the newest five, `{ since = \"0.3.0\" }` keeps that\nversion and newer, `{ releases_only = true }` keeps releases alone\n(no dev builds, no unreleased state); they combine. `--version`\ndocuments one version instead." } }, "type": "object" }, + "DocVersionSelect": { + "additionalProperties": false, + "description": "`[doc] versions` as a table: each key trims the list, and they combine\n(`releases_only` first, then `since`, then `last`).", + "properties": { + "last": { + "description": "Keep the newest N (the unreleased state counts as one).", + "format": "uint", + "minimum": 1, + "type": "integer" + }, + "releases_only": { + "default": false, + "description": "Keep releases only: no dev builds and no unreleased state.", + "type": "boolean" + }, + "since": { + "description": "Keep this built version (a version string) and every newer one.", + "type": "string" + } + }, + "type": "object" + }, + "DocVersions": { + "anyOf": [ + { + "allOf": [ + { + "$ref": "#/definitions/AllVersions" + } + ], + "description": "`\"all\"`: every release, dev build and the unreleased state." + }, + { + "allOf": [ + { + "$ref": "#/definitions/DocVersionSelect" + } + ], + "description": "A trimmed list." + } + ], + "description": "`[doc] versions`: every version, or a trimmed list." + }, "EncodingEntry": { "anyOf": [ { diff --git a/docs/docs/schemas/doc-model/1.json b/docs/docs/schemas/doc-model/1.json index 352b73c..64b8006 100644 --- a/docs/docs/schemas/doc-model/1.json +++ b/docs/docs/schemas/doc-model/1.json @@ -193,6 +193,48 @@ ], "type": "object" }, + { + "description": "An optional field added where a format in play can't tolerate it: it\nkeys fields by position, rejects an unknown field, or rejects a\nmissing optional one (its profile's `struct_fields`,\n`unknown_field`, `missing_optional`).", + "properties": { + "field_name": { + "type": "string" + }, + "field_type": { + "type": "string" + }, + "kind": { + "const": "added_optional_field", + "type": "string" + }, + "type_name": { + "type": "string" + } + }, + "required": [ + "kind", + "type_name", + "field_name", + "field_type" + ], + "type": "object" + }, + { + "description": "Fields kept their names but moved, where a format in play keys them\nby position (`struct_fields = by_position`).", + "properties": { + "kind": { + "const": "reordered_fields", + "type": "string" + }, + "type_name": { + "type": "string" + } + }, + "required": [ + "kind", + "type_name" + ], + "type": "object" + }, { "properties": { "field_name": { @@ -291,6 +333,23 @@ ], "type": "object" }, + { + "description": "Variants kept their names but moved (reordered, or one inserted\nbefore others), where a format in play encodes them by index\n(`enum_variants = by_index`).", + "properties": { + "enum_name": { + "type": "string" + }, + "kind": { + "const": "reordered_enum_variants", + "type": "string" + } + }, + "required": [ + "kind", + "enum_name" + ], + "type": "object" + }, { "properties": { "function_name": { @@ -311,6 +370,65 @@ ], "type": "object" }, + { + "description": "Functions kept their names but moved (reordered, or one inserted\nbefore others), where the protocol's framing calls them by index\n(`calls = by_index`).", + "properties": { + "kind": { + "const": "reordered_functions", + "type": "string" + }, + "protocol_name": { + "type": "string" + } + }, + "required": [ + "kind", + "protocol_name" + ], + "type": "object" + }, + { + "description": "A protocol renamed: one removed and one added with the same\nfunctions. Its name doesn't reach the wire, but consumers refer to it.", + "properties": { + "kind": { + "const": "renamed_protocol", + "type": "string" + }, + "new_name": { + "type": "string" + }, + "old_name": { + "type": "string" + } + }, + "required": [ + "kind", + "old_name", + "new_name" + ], + "type": "object" + }, + { + "description": "A schema file's namespace renamed: one removed and one added with\nthe same declarations. Consumers refer to it in paths.", + "properties": { + "kind": { + "const": "renamed_namespace", + "type": "string" + }, + "new_name": { + "type": "string" + }, + "old_name": { + "type": "string" + } + }, + "required": [ + "kind", + "old_name", + "new_name" + ], + "type": "object" + }, { "properties": { "details": { @@ -537,7 +655,7 @@ "type": "object" }, { - "description": "The validators applied to a declaration changed other than by pure\nremoval: what's accepted may have narrowed.", + "description": "The validators applied to a declaration changed other than by pure\nremoval: what's accepted may have narrowed. The set compared is the\neffective one: a field's own validators plus those of the aliases\nits type goes through. `target` may also be a constant whose value\nchanged while a validator argument uses it.", "properties": { "kind": { "const": "validation_tightened", @@ -849,7 +967,7 @@ "description": "Non-breaking modifications that may warrant a patch bump", "oneOf": [ { - "description": "A declaration's own docstring text changed with nothing else about\nit - doc/comment-only changes warrant a patch bump, not a\nmajor/minor one. Only tracked at the declaration level (struct,\nenum, protocol, const, error, alias, validator) for now, not\nper-field/per-function.", + "description": "A docstring's text changed: a declaration's (`S`) or a member's\n(`S.field`, `P.function`). Documentation only: a patch.", "properties": { "kind": { "const": "docstring_changed", @@ -865,6 +983,60 @@ ], "type": "object" }, + { + "description": "A type respelled without changing what it is: swapped for an\nequivalent alias, either way, or one alias for another with the same\ntarget (compared after resolving aliases, core#110). `target` is the\nfield (`S.f`), function (`P.f`), constant or alias.", + "properties": { + "kind": { + "const": "type_respelled", + "type": "string" + }, + "new_type": { + "type": "string" + }, + "old_type": { + "type": "string" + }, + "target": { + "type": "string" + } + }, + "required": [ + "kind", + "target", + "old_type", + "new_type" + ], + "type": "object" + }, + { + "description": "A constant's value changed where only field defaults use it:\ndefaults don't travel on the wire.", + "properties": { + "kind": { + "const": "changed_constant_value", + "type": "string" + }, + "name": { + "type": "string" + }, + "new_value": { + "type": [ + "string", + "null" + ] + }, + "old_value": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "kind", + "name" + ], + "type": "object" + }, { "properties": { "field_name": { @@ -1173,7 +1345,7 @@ "type": "object" }, { - "description": "A constant's value changed. Counted as minor for now: whether it\nreaches the wire (a validator argument, a default) isn't traced yet.", + "description": "A constant's value changed, and nothing on the wire uses it: no\nvalidator argument and no field default. (One a validator uses is\n[`BreakingChange::ValidationTightened`]; one only a default uses is\n[`Modification::ChangedConstantValue`].)", "properties": { "kind": { "const": "changed_constant_value", @@ -1893,7 +2065,7 @@ "type": "object" } }, - "description": "A package's documentation.", + "description": "A package's documentation.\n\nVersion 1 grows additively: new unit, type and change kinds and new\nfields that may be absent keep the version, so a reader skips kinds it\ndoesn't know and ignores unknown fields. Only an incompatible change\nbumps `model_version`.", "properties": { "changelog": { "default": [], @@ -1904,7 +2076,7 @@ "type": "array" }, "model_version": { - "description": "[`DOC_MODEL_VERSION`] when it was produced.", + "description": "The model's version when it was produced. Additive changes keep it;\nonly an incompatible one bumps it.", "format": "uint32", "minimum": 0, "type": "integer" diff --git a/scripts/sync-std-docs.py b/scripts/sync-std-docs.py index 2666a9b..0bc6d32 100755 --- a/scripts/sync-std-docs.py +++ b/scripts/sync-std-docs.py @@ -111,6 +111,11 @@ def main() -> int: out = tmp / "out" document(args.comline, package, out) + # A `comline doc` that documents every version (generation#101) + # writes `/markdown//`; std is never built, so its one + # version is the working tree, `unreleased`. + if (out / "markdown").is_dir(): + out = out / "markdown" / "unreleased" generated = pages(out) block = nav_block(out / "nav.yml") From da1327b4b649d780f5ed7fae4d85b88177ec0d41 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 1 Nov 2026 22:05:07 +0800 Subject: [PATCH 2/2] docs: the built-in renderers' cache key carries a content hash --- docs/docs/reference/tools/doc.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/reference/tools/doc.md b/docs/docs/reference/tools/doc.md index 1015886..6d6b7ca 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -61,8 +61,9 @@ docs/api/ **Caching.** A built version never changes, so its folder is kept between runs. `//.comline-doc.json` records each folder's key: the version's commit, the commit of the version before it, the renderer's id and -version (and the `comline` version for a built-in renderer, or the renderer -file's hash for `[doc] renderer`), the model version and `[doc] links`. A +version (for a built-in renderer, its crate version plus a content hash of +its sources and assets, `0.1.0+`, and the `comline` version; for +`[doc] renderer`, the renderer file's hash), the model version and `[doc] links`. A folder whose key still matches is left alone, so a run re-renders only the unreleased state and new versions. A folder for a version no longer listed (trimmed by `versions`, or the unreleased state once it's built) is removed.