Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 85 additions & 23 deletions docs/docs/guide/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
| `<module>.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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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 |

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate
| `comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--external-std] [--no-external-std] [--validate-on-decode <when>] [--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 = "<path>"`) and map [encodings](../guide/extending/encodings.md#5-map-it-to-a-type). |
| `comline release [1.0] [--raise <level> --reason <text>] [--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 <old> [<new>]` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`<new>` default). |
| `comline doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format <f>]` | 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 <dir>] [--version <v>] [--changelog-from <v>] [--format <f>]` | Write the package's documentation for every version (each release, dev build and the unreleased working state), each into `<out>/<format>/<version>/` 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 <command> [--encoding <name>]... [--corpus <dir>] [--timeout <secs>]` | 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`. |
Expand Down
10 changes: 6 additions & 4 deletions docs/docs/reference/congregation/comline-toml.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<out>/<format>/` 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 `<base>/<module>/#<anchor>`; 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
Expand Down
26 changes: 24 additions & 2 deletions docs/docs/reference/generator-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<site>/<version>/`, 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 |
Expand All @@ -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:

Expand Down
Loading
Loading