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
5 changes: 3 additions & 2 deletions docs/docs/guide/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
| `<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` | 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
Expand Down Expand Up @@ -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
Expand Down
23 changes: 16 additions & 7 deletions docs/docs/reference/tools/doc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
| `<module>.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. |

`<out>/markdown/index.md` lists the versions, newest first, grouped by release.
Expand All @@ -103,12 +103,17 @@ writes a self-contained static site per version with the same content:
|---|---|
| `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. |
| `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
Expand All @@ -131,12 +136,16 @@ At `<out>/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.
Expand Down
69 changes: 57 additions & 12 deletions docs/docs/schemas/doc-model/1.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -728,22 +728,37 @@
],
"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.",
"properties": {
"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"
},
Expand All @@ -753,7 +768,7 @@
"modifications": {
"description": "The rest: a patch bump.",
"items": {
"$ref": "#/definitions/Modification"
"$ref": "#/definitions/ModificationEntry"
},
"type": "array"
},
Expand Down Expand Up @@ -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.",
Expand Down Expand Up @@ -1106,7 +1121,22 @@
],
"type": "object"
}
]
],
"properties": {
"new": {
"type": [
"string",
"null"
]
},
"old": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"Module": {
"description": "One schema file.",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -1467,7 +1497,22 @@
],
"type": "object"
}
]
],
"properties": {
"new": {
"type": [
"string",
"null"
]
},
"old": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"Package": {
"properties": {
Expand Down
Loading