From 9b8e6a0eea8a5cba0752f2874e23bdf2b20f1641 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 1 Nov 2026 22:44:07 +0800 Subject: [PATCH] docs: comline doc's changelog entries and theme toggle The changelog shows each entry's severity, a linked title, and its old and new IDL lines (a diff block in Markdown, highlighted in HTML); the HTML header has a theme toggle. The doc-model schema copy picks up the entries' optional old/new fields. --- docs/docs/guide/documenting.md | 5 ++- docs/docs/reference/tools/doc.md | 23 +++++++--- docs/docs/schemas/doc-model/1.json | 69 ++++++++++++++++++++++++------ 3 files changed, 76 insertions(+), 21 deletions(-) diff --git a/docs/docs/guide/documenting.md b/docs/docs/guide/documenting.md index 6b93f12..f5ba8e4 100644 --- a/docs/docs/guide/documenting.md +++ b/docs/docs/guide/documenting.md @@ -63,7 +63,7 @@ version's folder has these pages: |---|---| | `index.md` | The package's name and version, its `config.idp` header, and a table of its modules. | | `.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. | +| `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. | | `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 @@ -104,7 +104,8 @@ 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. + 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 overview, with a note, when it doesn't have them. Dev builds are grouped under diff --git a/docs/docs/reference/tools/doc.md b/docs/docs/reference/tools/doc.md index 6d6b7ca..1e80371 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -79,7 +79,7 @@ version's folder: |---|---| | `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. | +| `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. | `/markdown/index.md` lists the versions, newest first, grouped by release. @@ -103,12 +103,17 @@ 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`. | -| `style.css` | The theme: fixed, light and dark following the OS setting. | +| `changelog.html` | With a changelog: as `changelog.md`, with a severity badge, and the old and new lines marked `−` and `+` and syntax-highlighted. | +| `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, and -a version picker in the header: +Every page has a sidebar of modules and their declarations, a search box, a +theme toggle, and a version picker in the header: + +- 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 + pages and versions, and is applied before the page paints. Where storage is + blocked it lasts for the page. - The picker is a native drop-down, newest first, with dev builds grouped under the release they lead to, and a Go button. Choosing a version with the mouse @@ -131,12 +136,16 @@ At `/html/`, the site's root: | `style.css` | The same theme. | On `compare.html`, two versions show what changed between them, grouped by -unit, each change labelled major, minor or patch, with the step it came from. +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. 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 -before it (breaking is major, a feature minor, anything else patch), and the +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 grid's cells are structural only. Doc text is rendered from Markdown to HTML; raw HTML in it is shown as text. diff --git a/docs/docs/schemas/doc-model/1.json b/docs/docs/schemas/doc-model/1.json index 64b8006..74529cf 100644 --- a/docs/docs/schemas/doc-model/1.json +++ b/docs/docs/schemas/doc-model/1.json @@ -113,8 +113,8 @@ ], "type": "object" }, - "BreakingChange": { - "description": "Breaking changes that require a major version bump", + "BreakingChangeEntry": { + "description": "One change, as `comline diff` reports it (its `kind` and that kind's\nfields), with the IDL it's about: one line of the declaration or member\nbefore (`old`) and after (`new`), printed from the frozen schemas. An\naddition has only `new`, a removal only `old`, and a kind with nothing\nto print as IDL (a docstring change, an error's ordinal) neither.", "oneOf": [ { "properties": { @@ -728,7 +728,22 @@ ], "type": "object" } - ] + ], + "properties": { + "new": { + "type": [ + "string", + "null" + ] + }, + "old": { + "type": [ + "string", + "null" + ] + } + }, + "type": "object" }, "Changelog": { "description": "What changed from one version to another, as `comline diff` reports it.\n\nNames in it are as the declarations write them, not qualified by\nmodule.", @@ -736,14 +751,14 @@ "breaking": { "description": "Changes an older peer can't work with: a major bump.", "items": { - "$ref": "#/definitions/BreakingChange" + "$ref": "#/definitions/BreakingChangeEntry" }, "type": "array" }, "features": { "description": "Additions: a minor bump.", "items": { - "$ref": "#/definitions/NewFeature" + "$ref": "#/definitions/NewFeatureEntry" }, "type": "array" }, @@ -753,7 +768,7 @@ "modifications": { "description": "The rest: a patch bump.", "items": { - "$ref": "#/definitions/Modification" + "$ref": "#/definitions/ModificationEntry" }, "type": "array" }, @@ -963,8 +978,8 @@ ], "type": "object" }, - "Modification": { - "description": "Non-breaking modifications that may warrant a patch bump", + "ModificationEntry": { + "description": "One change, as `comline diff` reports it (its `kind` and that kind's\nfields), with the IDL it's about: one line of the declaration or member\nbefore (`old`) and after (`new`), printed from the frozen schemas. An\naddition has only `new`, a removal only `old`, and a kind with nothing\nto print as IDL (a docstring change, an error's ordinal) neither.", "oneOf": [ { "description": "A docstring's text changed: a declaration's (`S`) or a member's\n(`S.field`, `P.function`). Documentation only: a patch.", @@ -1106,7 +1121,22 @@ ], "type": "object" } - ] + ], + "properties": { + "new": { + "type": [ + "string", + "null" + ] + }, + "old": { + "type": [ + "string", + "null" + ] + } + }, + "type": "object" }, "Module": { "description": "One schema file.", @@ -1136,8 +1166,8 @@ ], "type": "object" }, - "NewFeature": { - "description": "New features that require a minor version bump", + "NewFeatureEntry": { + "description": "One change, as `comline diff` reports it (its `kind` and that kind's\nfields), with the IDL it's about: one line of the declaration or member\nbefore (`old`) and after (`new`), printed from the frozen schemas. An\naddition has only `new`, a removal only `old`, and a kind with nothing\nto print as IDL (a docstring change, an error's ordinal) neither.", "oneOf": [ { "properties": { @@ -1467,7 +1497,22 @@ ], "type": "object" } - ] + ], + "properties": { + "new": { + "type": [ + "string", + "null" + ] + }, + "old": { + "type": [ + "string", + "null" + ] + } + }, + "type": "object" }, "Package": { "properties": {