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
19 changes: 18 additions & 1 deletion docs/docs/guide/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`.
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`), 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: 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 <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
2 changes: 1 addition & 1 deletion docs/docs/reference/congregation/comline-toml.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<base>/<module>/#<anchor>`; one that isn't is plain text. |
Expand Down
21 changes: 19 additions & 2 deletions docs/docs/reference/tools/doc.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# comline doc

```
comline doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format markdown|json]
comline doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format markdown|html|json]
```

`comline doc` writes a package's documentation. Like `comline check`, it writes
Expand All @@ -15,7 +15,7 @@ nothing to `.comline/`. For a walkthrough, see
| `--out <dir>` | `[doc] out`, else `docs/api` | Where to write, relative to the project. |
| `--version <v>` | the working tree | Document a built version: a version string, a commit hash (4+ characters), or `HEAD`. |
| `--changelog-from <v>` | `[doc] changelog_from` | Add what changed from built version `<v>` to the documented one. |
| `--format <f>` | `[doc] format`, else `markdown` | `markdown`, `json`, or another renderer id `[doc] renderer` offers. |
| `--format <f>` | `[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).

Expand All @@ -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`. |
| `<module>.html` | As `<module>.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).

Expand Down
3 changes: 2 additions & 1 deletion docs/docs/schemas/comline-toml/0.x.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading