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..6d6b7ca 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -1,27 +1,79 @@ # 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 (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. +`--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 +82,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 +97,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 +107,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 +171,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")