From 677b77a9a6db2ae5028f450148dd085a30188e57 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Mon, 2 Nov 2026 11:42:31 +0800 Subject: [PATCH] docs: comline doc open and --open; Type and Value columns in the module table --- docs/docs/guide/documenting.md | 6 ++++++ docs/docs/reference/cli.md | 2 +- docs/docs/reference/tools/doc.md | 26 ++++++++++++++++++++++++-- 3 files changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/docs/guide/documenting.md b/docs/docs/guide/documenting.md index 9d65aaf..44f6281 100644 --- a/docs/docs/guide/documenting.md +++ b/docs/docs/guide/documenting.md @@ -74,6 +74,12 @@ 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. +To look at the result, `comline doc open` opens it (the HTML site if you +render one, else the first format you configured), rendering it first when +there is nothing to open; `comline doc --open` renders, then opens. HTML opens +in the browser `$BROWSER` names, else your default one. See +[comline doc](../reference/tools/doc.md#opening-the-result). + ### Put them on a site The pages are plain Markdown, so they drop into an mkdocs or zensical site: diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 7052989..6976ceb 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 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 doc [--out ] [--version ] [--changelog-from ] [--format ] [--open]` | 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]`. `comline doc open []` (or `--open` after a render) opens the result with the system's default handler, rendering first if it isn't there. 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/tools/doc.md b/docs/docs/reference/tools/doc.md index a206b33..4cd18b3 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -1,7 +1,8 @@ # comline doc ``` -comline doc [--out ] [--version ] [--changelog-from ] [--format [,...]] +comline doc [--out ] [--version ] [--changelog-from ] [--format [,...]] [--open] +comline doc open [] [--out ] ``` `comline doc` writes a package's documentation for every version: each @@ -17,6 +18,27 @@ walkthrough, see [Documenting your schemas](../../guide/documenting.md). | `--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. | +| `--open` | off | After rendering, open the first format's index, as `comline doc open` does. With `--version`, it opens that version's own `index.html` or `index.md` (`model.json` for `json`). | + +## Opening the result + +`comline doc open []` opens the generated documentation with the +system's default handler: `//index.html`, `index.md` or +`index.json`, for `html`, `markdown` or `json`. `--out` is read as `comline doc` +reads it. + +- With no ``, it opens `html` if that is among `[doc] formats`, else + the first configured format. +- If the file isn't there, it renders that format first, exactly as + `comline doc --format ` would. If it is, it opens it as it is, + without re-rendering, and says so in one line with how to refresh it + (`comline doc --format `). +- HTML opens in the browser named by `$BROWSER`, else the system's default; + Markdown and JSON open in whatever the system associates with the file. +- It prints the absolute path it opens. With no display, or when nothing + opens, it prints that path and a hint instead, and exits `0`. + +`comline doc --open` is the same after a render, as `cargo doc --open` is. The `[doc]` keys are in [`comline.toml`](../congregation/comline-toml.md#doc), including `versions`, which trims the list of versions. @@ -87,7 +109,7 @@ version's folder: | File | Contents | |---|---| | `index.md` | Package name and version, its `config.idp` `//!` header, a module table (Module, Summary), a Dependencies table (each dependency and the modules of it the package uses), a link to the changelog. | -| `.md` | Per schema (`types::user` → `types/user.md`): its `//!` header, a table of its declarations (Item, Summary), then each one with its `///` docs, annotations, fields and arguments (a field's own docs, else its parent's `/// @name:` line), enum variants, an error's ordinal and message, a validator's targets, parameters and asserts, and each protocol's functions and wire summary. | +| `.md` | Per schema (`types::user` → `types/user.md`): its `//!` header, a table of its declarations (Item, Summary, then Type and Value, each only when some declaration in the module has one: a constant's type and value, a type alias's target), then each one with its `///` docs, annotations, fields and arguments (a field's own docs, else its parent's `/// @name:` line), enum variants, an error's ordinal and message, a validator's targets, parameters and asserts, and each protocol's functions and wire summary. | | `changelog.md` | With a changelog: breaking changes, additions and other changes. Each entry is a heading line (its severity, `MAJOR`, `MINOR` or `PATCH`, and a title such as `` `Orders.place`: signature changed `` linking to the declaration), then the change as a fenced `diff` block: the old IDL line with `-`, the new with `+`. An addition has only the `+` line, a removal only the `-` line, and a change with no IDL to show (a docstring, an error's ordinal, guarantees) a sentence instead. A release shows its changes since the previous release; a dev build its step, then a link to its changes since the last release, listed below it. | | `deps//.md` | Per module of a dependency without a published base URL: what the package reaches of it, as `.md`. | | `nav.yml` | A `nav` list for mkdocs or zensical: the package's modules, then a `Dependencies` section (a dependency's pages, or its published base URL). |