From b584934c12dff436e49b5fcbac3562d242919b49 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 1 Nov 2026 23:48:42 +0800 Subject: [PATCH] docs: comline doc lists dependencies apart; a release's changelog since the previous release - Only the package's own modules are its modules; what it reaches of each dependency and std is listed apart (sidebar section, index table, nav), with pages for a dependency without a published URL. std links to its hosted docs by default. - A release's changelog page shows everything since the previous release; a dev build's its step and a link to everything since the last release. - The header shows the package name alone; module tables have column titles. - doc-model/1.json synced with core#163 (dependencies, changelog span). --- docs/docs/guide/documenting.md | 38 ++++++++------ docs/docs/reference/tools/doc.md | 79 +++++++++++++++++++++++------- docs/docs/schemas/doc-model/1.json | 56 +++++++++++++++++++++ 3 files changed, 139 insertions(+), 34 deletions(-) diff --git a/docs/docs/guide/documenting.md b/docs/docs/guide/documenting.md index f5ba8e4..9d65aaf 100644 --- a/docs/docs/guide/documenting.md +++ b/docs/docs/guide/documenting.md @@ -61,9 +61,9 @@ 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. | +| `index.md` | The package's name and version, its `config.idp` header, a table of its modules, and a table of its dependencies. | | `.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` | What changed since the version before it, as `comline diff` reports it: each change's severity and a short title, then the old and new IDL lines as a `diff` block. | +| `changelog.md` | What changed, as `comline diff` reports it: each change's severity and a short title, then the old and new IDL lines as a `diff` block. A release shows everything since the previous release; a dev build what changed since the build before it, with a link to everything since the last release. | | `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 @@ -103,8 +103,8 @@ 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 +- **Each page** has a sidebar of your modules and their declarations, then a + collapsed Dependencies section, and a search box over every declaration. The theme follows the OS's light or dark setting until you pick one with the toggle in the header, which the site remembers. - **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 @@ -129,10 +129,17 @@ formats = ["html", "markdown"] The site is generated, so a new project's `.gitignore` (from `comline new`) leaves out `docs/api/html/`. -### Link to dependencies +### Dependencies -A type from a dependency or `std` is plain text, unless you say where that -package's docs live. Give each one a base URL in `comline.toml`: +Your docs document your package. What it uses of each dependency, and of +`std`, is listed apart, under Dependencies in the sidebar and the index: only +the declarations your own use, and what those use in turn, never the whole +dependency. Each dependency gets its own pages (`deps//`), and +a type from it links there. + +`std` links to its hosted docs instead, `https://comlineproject.github.io/docs/std/`. +To link another dependency to its published docs rather than render pages for +it, give it a base URL in `comline.toml`: ```toml [doc] @@ -141,7 +148,8 @@ links = { std = "https://example.com/std", billing = "https://docs.example.com/b 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. +anchor, in the directory-URL form mkdocs and zensical publish pages at. A +`links` entry for `std` replaces its default. ## 3. Choose the versions @@ -171,10 +179,9 @@ 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. +the headers it was built with, even after the sources change. One thing needs +the source: protocols in a built version have no wire summary. 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 @@ -214,7 +221,6 @@ 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. 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`. +pages of this site rather than a separate one. A type from `std` in your own +docs links to them by default, 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/tools/doc.md b/docs/docs/reference/tools/doc.md index 1e80371..a206b33 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -52,15 +52,24 @@ docs/api/ the release it leads to (`0.2.0`). - The working tree appears as `unreleased` only when its schemas or headers differ from the last build. With nothing built, it is the only version. -- Each version carries the changelog from the version before it in the list, - computed by core with the same rules as `comline diff`. The first version - has none. +- Each version carries the changelog from the version before it in the list + (a step), computed by core with the same rules as `comline diff`. The first + version has none. +- A release also carries everything since the previous release, compared + directly between the two built versions, and its changelog page shows that + (`0.1.0 to 0.2.0`), not the step. A release built from the same files as its + last dev build still lists that dev build's changes. The first release, with + none before it, shows its step. +- A dev build (or the unreleased state) after the first build following a + release carries its changes since that release too: its page shows its step + and links to them. These are measured from the real previous release even + when `versions` trims it away. - The latest version, which `index.html` points at, is the newest release, else the newest dev build, else the unreleased state. **Caching.** A built version never changes, so its folder is kept between runs. `//.comline-doc.json` records each folder's key: the -version's commit, the commit of the version before it, the renderer's id and +version's commit, the commits its changelogs start from, the renderer's id and version (for a built-in renderer, its crate version plus a content hash of its sources and assets, `0.1.0+`, and the `comline` version; for `[doc] renderer`, the renderer file's hash), the model version and `[doc] links`. A @@ -77,10 +86,11 @@ version's folder: | File | Contents | |---|---| -| `index.md` | Package name and version, its `config.idp` `//!` header, a module table, a link to the changelog. | -| `.md` | Per schema (`types::user` → `types/user.md`): its `//!` header, a table of its declarations, 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. | -| `nav.yml` | A `nav` list for mkdocs or zensical. | +| `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. | +| `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). | `/markdown/index.md` lists the versions, newest first, grouped by release. There is no version picker: switching versions on a published site is left to @@ -90,7 +100,17 @@ each version folder as a version of the site and adds a version selector. Each declaration has an anchor, its name in lowercase; a function has `-`. A type links to its declaration's anchor. A type from a dependency links to `//#` when `[doc] links` gives the -dependency a base URL, and is plain text otherwise. +dependency a base URL; `std` defaults to the hosted std docs, +`https://comlineproject.github.io/docs/std/` (`std::http::HttpMethod` links to +`.../std/http/#httpmethod`). Otherwise it links to the dependency's own pages, +`deps//.md`, and is plain text only when the package doesn't +reach that declaration. + +**Dependencies.** Only the package's own modules are its modules. What it +reaches of each dependency, and of `std`, is listed apart: the declarations its +own use or re-export and what those use in turn, the same reach +[versioning](../versioning.md#dependencies) measures a dependency by. A dependency it reaches +nothing of isn't listed. The wire summary has the rows [`comline inspect`](inspect.md) prints: the format, framing and handshake with where each came from, then each guarantee, @@ -103,12 +123,32 @@ writes a self-contained static site per version with the same content: |---|---| | `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`, with a severity badge, and the old and new lines marked `−` and `+` and syntax-highlighted. | +| `changelog.html` | With a changelog: as `changelog.md`, with a severity badge, and the old and new lines marked `−` and `+` and syntax-highlighted. A dev build's changes since the last release are a collapsed section the line under its step opens. | +| `deps//.html` | As `deps//.md`. | | `style.css` | The theme: fixed, light and dark following the OS setting unless the header's toggle picks one. | | `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, a search box, a -theme toggle, and a version picker in the header: +Every page has a header with the package's name (the version is in the +picker beside it), a search box, a theme toggle and a version picker, and a +sidebar: the package's modules and their declarations, then a Dependencies +section, collapsed unless the page is a dependency's, with one group per +dependency. A group links to the dependency's published docs when it has a +base URL, else to its pages here: + +```text +Overview +api + struct Order ... +types +Dependencies (collapsed) + localdeps + greeting -> deps/localdeps/greeting.html + std ↗ -> https://comlineproject.github.io/docs/std/ + http -> .../std/http/ +Changelog +``` + +The header and sidebar work like this: - The theme toggle cycles auto (the OS setting), light and dark. The choice is kept in the browser's `localStorage` where it's allowed, so it carries across @@ -138,15 +178,16 @@ At `/html/`, the site's root: On `compare.html`, two versions show what changed between them, grouped by unit, each change shown as on `changelog.html` (badge, title, highlighted old and new lines), with the step it came from. The root's pages have the theme -toggle too. +toggle too, and show the package's name alone. More versions show a grid with units and members as rows and the chosen versions as columns. Each cell is the type or signature, or "absent", and a unit's badge is the largest change across the range. The labels are never -computed in the browser. Core computes each version's changelog from the one +computed in the browser. Core computes each version's step from the one before it (breaking is major, a feature minor, anything else patch), along with each entry's old and new IDL lines (the documentation model's optional `old` and `new` on a changelog entry), and the -page only collects the steps after the older version up to the newer one. The +page only collects the steps after the older version up to the newer one, never +a release's changes since the previous release. The grid's cells are structural only. 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` @@ -159,15 +200,17 @@ shape of [`doc-model/1.json`](../../schemas/doc-model/1.json), and and each version's `id`, `release`, `kind` and model path. Version 1 of the model grows additively: new kinds and fields that may be absent keep the version, so a reader should skip a `kind` it doesn't know and ignore unknown -fields. +fields. `dependencies` lists what the package reaches of each dependency +(`package`, and `modules` holding only the units reached), and a changelog's +`span` says what it covers: `step` (the default, when absent), `release` or +`since_release`. ## Built versions A built version's model comes from its frozen IR and the `//!` headers stored with it. A built version keeps no source, so: -- its protocols have no wire summary; -- a type from a dependency has no link. +- its protocols have no wire summary. A version built before headers were stored has no headers. Each page of such a version opens with a note saying what it lacks, in both formats. diff --git a/docs/docs/schemas/doc-model/1.json b/docs/docs/schemas/doc-model/1.json index 74529cf..1d1c61c 100644 --- a/docs/docs/schemas/doc-model/1.json +++ b/docs/docs/schemas/doc-model/1.json @@ -772,6 +772,14 @@ }, "type": "array" }, + "span": { + "allOf": [ + { + "$ref": "#/definitions/ChangelogSpan" + } + ], + "description": "Which versions it spans. Absent means [`ChangelogSpan::Step`]." + }, "to": { "type": "string" } @@ -785,6 +793,26 @@ ], "type": "object" }, + "ChangelogSpan": { + "description": "Which versions a [`Changelog`] spans.", + "oneOf": [ + { + "const": "step", + "description": "From the version just before `to`: one step of the history. A\ncomparison across versions composes these.", + "type": "string" + }, + { + "const": "release", + "description": "A release's changes since the previous release (`from`): what the\nrelease's changelog shows, its dev builds' steps composed.", + "type": "string" + }, + { + "const": "since_release", + "description": "A dev build's (or the unreleased state's) changes since the last\nrelease (`from`): everything the release it leads to holds so far.", + "type": "string" + } + ] + }, "Choice": { "description": "A resolved encoding: its name, its parameters and where it came from.", "properties": { @@ -810,6 +838,27 @@ ], "type": "object" }, + "Dependency": { + "description": "A dependency (or `std`), as far as the documented package reaches it.", + "properties": { + "modules": { + "description": "Its modules the package reaches anything of, each with only the\nunits reached, in declaration order. A module's path is within the\ndependency (`http`, not `std::http`); its header isn't kept.", + "items": { + "$ref": "#/definitions/Module" + }, + "type": "array" + }, + "package": { + "description": "Its name, as the documented package names it (`std` for the\nstandard library); a [`UnitRef::package`] to it says the same.", + "type": "string" + } + }, + "required": [ + "package", + "modules" + ], + "type": "object" + }, "Doc": { "description": "A `///` docstring: its description and its `/// @name: ...` lines.", "properties": { @@ -2120,6 +2169,13 @@ }, "type": "array" }, + "dependencies": { + "description": "What the package reaches of each dependency, `std` included: one\nentry per dependency package it reaches anything of, by name, in\nname order. Not the package's own: its modules hold only the\ndeclarations the package's own use or re-export, and what those use.\nAbsent in a model from before it was added.", + "items": { + "$ref": "#/definitions/Dependency" + }, + "type": "array" + }, "model_version": { "description": "The model's version when it was produced. Additive changes keep it;\nonly an incompatible one bumps it.", "format": "uint32",