From 691faacfa759c42f340e5c2fbfa63689dae962e3 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 1 Nov 2026 16:39:02 +0800 Subject: [PATCH] docs: comline doc --format html The CLI reference, the comline doc and comline.toml references and the documenting guide cover the official HTML renderer: --format html and [doc] format = "html". schemas/comline-toml/0.x.json is refreshed, and the guide notes that the std pages are rendered with Markdown, as pages of this site. --- docs/docs/guide/documenting.md | 19 ++++++++++++++++- docs/docs/reference/cli.md | 2 +- .../reference/congregation/comline-toml.md | 2 +- docs/docs/reference/tools/doc.md | 21 +++++++++++++++++-- docs/docs/schemas/comline-toml/0.x.json | 3 ++- 5 files changed, 41 insertions(+), 6 deletions(-) diff --git a/docs/docs/guide/documenting.md b/docs/docs/guide/documenting.md index b3cd8bb..6a64827 100644 --- a/docs/docs/guide/documenting.md +++ b/docs/docs/guide/documenting.md @@ -65,6 +65,22 @@ render into the site's `docs/` tree and copy `nav.yml`'s entries into comline doc --out site/docs/api ``` +### Or as a site of its own + +`--format html` writes a finished static site instead, with the same content +as the Markdown pages: + +```bash +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`. + ### Link to dependencies A type from a dependency or `std` is plain text, unless you say where that @@ -134,7 +150,8 @@ and the flag wins: The standard library is rendered this way, and is the live example: the [`std` pages](../std/index.md) are `comline doc` run over std's own package, -with nothing written by hand. A type from `std` in your own docs links to them +with nothing written by hand. They use the Markdown format, so they become +pages of this site rather than a separate one. A type from `std` in your own docs links to them with `links = { std = "https://comlineproject.github.io/docs/std" }`, so `std::http::Request` in a field's type links to `https://comlineproject.github.io/docs/std/http/#request`. diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 008360e..ac746b5 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`), 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: 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 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 a02ddec..8a81e4f 100644 --- a/docs/docs/reference/congregation/comline-toml.md +++ b/docs/docs/reference/congregation/comline-toml.md @@ -207,7 +207,7 @@ 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), `json` (the documentation model, `model.json`), or another renderer id `renderer` offers. `--format` 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. | | `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. | diff --git a/docs/docs/reference/tools/doc.md b/docs/docs/reference/tools/doc.md index 503450d..44d517c 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -1,7 +1,7 @@ # comline doc ``` -comline doc [--out ] [--version ] [--changelog-from ] [--format markdown|json] +comline doc [--out ] [--version ] [--changelog-from ] [--format markdown|html|json] ``` `comline doc` writes a package's documentation. Like `comline check`, it writes @@ -15,7 +15,7 @@ nothing to `.comline/`. For a walkthrough, see | `--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`, `json`, or another renderer id `[doc] renderer` offers. | +| `--format ` | `[doc] format`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. | The `[doc]` keys are in [`comline.toml`](../congregation/comline-toml.md#doc). @@ -39,6 +39,23 @@ The wire summary has the rows [`comline inspect`](inspect.md) prints: the 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: + +| File | Contents | +|---|---| +| `index.html` | As `index.md`. | +| `.html` | As `.md` (`types::user` → `types/user.html`), with the same anchors. | +| `changelog.html` | With a changelog: as `changelog.md`. | +| `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. +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). diff --git a/docs/docs/schemas/comline-toml/0.x.json b/docs/docs/schemas/comline-toml/0.x.json index 5dc8b31..6a35e16 100644 --- a/docs/docs/schemas/comline-toml/0.x.json +++ b/docs/docs/schemas/comline-toml/0.x.json @@ -13,9 +13,10 @@ }, "format": { "default": "markdown", - "description": "What to write: `markdown` (pages, from the official renderer or\n`renderer`), `json` (the documentation model itself, `model.json`), or\nanother renderer id `renderer` offers. Default `markdown`. `--format`\noverrides it.", + "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.", "examples": [ "markdown", + "html", "json" ], "type": "string"