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
6 changes: 6 additions & 0 deletions docs/docs/guide/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
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 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 doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format <f>] [--open]` | 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]`. `comline doc open [<format>]` (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 <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
26 changes: 24 additions & 2 deletions docs/docs/reference/tools/doc.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# comline doc

```
comline doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format <f>[,<f>...]]
comline doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format <f>[,<f>...]] [--open]
comline doc open [<format>] [--out <dir>]
```

`comline doc` writes a package's documentation for every version: each
Expand All @@ -17,6 +18,27 @@ walkthrough, see [Documenting your schemas](../../guide/documenting.md).
| `--version <v>` | every version | Document only this built version, into `<out>/<format>/<v>/`: a version string, a commit hash (4+ characters), or `HEAD`. |
| `--changelog-from <v>` | `[doc] changelog_from` | With `--version`: add what changed from built version `<v>` to the documented one. |
| `--format <f>` | `[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 [<format>]` opens the generated documentation with the
system's default handler: `<out>/<format>/index.html`, `index.md` or
`index.json`, for `html`, `markdown` or `json`. `--out` is read as `comline doc`
reads it.

- With no `<format>`, 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 <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 <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.
Expand Down Expand Up @@ -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. |
| `<module>.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. |
| `<module>.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/<package>/<module>.md` | Per module of a dependency without a published base URL: what the package reaches of it, as `<module>.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). |
Expand Down
Loading