Writing documentation¶
The documentation is a Zensical site built from zensical.toml and
the Markdown pages in docs/. Part of the reference is generated from the code. Checks fail when
it is out of date or when a page shows a command that does not exist, so the pages cannot drift
from what chalkos does. This page explains how the site is organised, built, generated, checked
and published. What goes into a page, and how it is worded, is the
docs style guide's subject.
Site sections¶
The navigation has one section per reader and two that every reader shares:
| Section | Directory | Reader | Kinds of page |
|---|---|---|---|
| Get started | get-started/ |
a reader new to chalkos | explanation, tutorial |
| Guides | guides/ |
an operator or image author who follows one project through | tutorial |
| Operate nodes | operate/ |
operator | how-to |
| Run Kubernetes | kubernetes/ |
operator running Kubernetes | how-to |
| Run a router | router/ |
operator running routers | how-to |
| Build images | build/ |
image author | how-to |
| How chalkos works | how-it-works/node/, how-it-works/kubernetes/, how-it-works/router/ |
everyone | explanation |
| Reference | reference/ |
everyone | reference |
| Contribute | contribute/ |
contributor | how-to, explanation |
Each section is a tab in the site's header, so the sidebar lists the pages of one section at a time. A section of more than about six pages splits them into groups of two to seven, such as Set up, Day 2 and Diagnose and recover in Operate nodes. Each section starts with an index page whose headings are its groups, with a card for each page. The docs style guide describes the readers, and the page templates describe the kinds of page.
zensical.toml sets the site's name, theme and navigation. The navigation lists every page;
the region between # BEGIN docgen cli and # END docgen cli is generated, and the rest is
written by hand.
Build and preview the site¶
Serve the working tree while editing:
Zensical serves a copy of docs/ without docs/superpowers, which git ignores, and the copy is
kept in sync every second, so a saved page appears after a reload. Pass Zensical's own options
after --.
Build the site as it is published:
The build sees only the files git tracks, so git add a new page before building it. It runs
zensical build --strict, which fails on a link to a page or an anchor that does not exist.
Generated pages¶
These pages are generated and never edited by hand:
| Page | Generated from | By |
|---|---|---|
docs/reference/cli/ |
the command trees of chalkctl, chalklab, chalkbuild and chalkcfg, with their help in pkg/chalkctl/help.go, pkg/chalkctl/layers/*/help.go, pkg/chalklab/help.go, pkg/chalkbuild/help.go and pkg/chalkcfg/help.go |
docgen cli |
docs/reference/kinds.md |
the JSON Schemas of the kinds of an image with the Kubernetes layer and of a router image's, declared in modules/node/kinds/builtin/, modules/node/kubernetes/kinds.nix and the kinds.nix files of modules/node/router/, and of the inventory and the lab file, pkg/inventory/chalkctl.chalkos.dev_v1alpha1_Inventory.json and pkg/chalklab/chalklab.chalkos.dev_v1alpha1_Lab.json |
docgen kinds |
docs/reference/mkimages.md, docs/reference/image-options.md, docs/reference/extension-api.md |
the arguments of mkImage and mkImages in lib/images-arguments.nix and the option declarations of the node modules, as nixosOptionsDoc's JSON; their openings, and the table of chalkosLib that ends the extension API, in nix/docs/templates |
docgen options |
docs/reference/builtins.md |
the schemas, facts.json, outputs.json and effects.json of an image with the Kubernetes layer, of one without a layer and of a router image, which the node modules in modules/node/ declare |
docgen builtins |
docs/reference/api.md |
the proto files of the node API and of each layer's API, api/chalkos/*/v1/*.proto, through the template api/markdown.tmpl |
protoc-gen-doc in buf.gen.yaml |
the navigation region of zensical.toml |
the command trees | docgen cli |
docs/includes/abbreviations.md |
the first sentence of each entry of docs/reference/glossary.md |
docgen abbr |
To change one, change its source and regenerate all of them:
The docgen app runs the script docs.write of nix/docs/default.nix, which copies the output of the
derivation docs.reference into the working tree, so it writes exactly what the check compares.
Run it in the repository's root, where zensical.toml is; elsewhere it refuses. Commit the source
and the generated pages together.
Glossary tooltips¶
Every page shows a glossary term's definition as a tooltip when the reader hovers over the term.
docgen abbr turns each entry of docs/reference/glossary.md into lines of Python-Markdown's
abbr syntax in docs/includes/abbreviations.md, and pymdownx.snippets appends that file to every
page. Terms in code get no tooltip; terms in headings and link text do.
## Slot { #slot }
<!-- abbr: slots, Slots -->
A pair of partitions that holds one image's store: the erofs data and its dm-verity hash tree.
They are labelled ...
This entry produces one line for each form of the term. The definition is the first sentence, with links and backticks removed:
*[Slots]: A pair of partitions that holds one image's store: the erofs data and its dm-verity hash tree.
*[slots]: A pair of partitions that holds one image's store: the erofs data and its dm-verity hash tree.
*[Slot]: A pair of partitions that holds one image's store: the erofs data and its dm-verity hash tree.
*[slot]: A pair of partitions that holds one image's store: the erofs data and its dm-verity hash tree.
A term's forms are its heading, the forms its <!-- abbr: ... --> comment lists, and the heading
with a lower-case first letter. The lower-case form exists only when the heading's first word is
capitalised and no later word is, so Secure Boot gets no "secure Boot". The comment takes two
keywords:
nolowerdrops the lower-case form. Effect has<!-- abbr: nolower, Effects, effects -->, so "take effect" gets no tooltip.nonegives the term no tooltip. Use it for a term that is mostly an ordinary word: Admin, Config, Identity, Image, Kind, Lab, Node, Operator, Output, Reader and Upgrade have it.
The longer form wins where two overlap, so "client files" is matched before "client file", and "config slot" before "slot". Tooltips have no underline until the pointer is over them, so they do not clutter the text. Readers on touch screens do not see them, which is acceptable because every term is also in the glossary.
nix run .#docs-serve does not regenerate the tooltips. After changing the glossary, run
nix run .#docgen, reload the page, and commit both files.
Code blocks¶
Pick the fence by what the block holds:
| Content | Fence | Prompt |
|---|---|---|
| A command with its output | console |
$ before each command; output lines without one |
| Commands without output, to run or copy | sh |
none |
| A script file | sh with title="name.sh" |
none |
| Output alone, logs, console text | text |
none |
| Nix, JSON, YAML, TOML | nix, json, yaml, toml |
none |
Output comes from a real run. Shorten long output with a line holding only ..., and leave the
rest unchanged. Break a command longer than about 100 characters with \ and indent the
continuation by two spaces.
A block that is a file names it in its title, such as title="nodes/w1.yaml". Show whole config
documents, with apiVersion, kind, metadata.name and spec, so docgen yaml checks them.
A value the reader replaces is a placeholder in angle brackets, such as <node> or <db-key>.
Explain each one next to the block. Tutorials use the lab's real names, cp1 and w1, instead.
A whole config document uses concrete names, because docgen yaml refuses <node> as a name.
Write a placeholder flag value with =, as in --fingerprint=<fingerprint>. Without it, the
shell and docgen check read the < as a redirection and report the flag as missing its value.
A comment in a block explains a decision, not the next line:
# A single control plane has no API server while it reboots.
Links¶
Links between pages use relative paths to the Markdown file, such as
[the image](../how-it-works/node/image.md#the-root-hash-identifies-an-image). The strict build fails on a missing page or
anchor. The generated reference has predictable anchors:
| Target | Path and anchor |
|---|---|
| A command | reference/cli/ and the command path joined with underscores: cli/chalkctl_etcd_leave.md; a flag is #flag- and its long name: cli/chalkctl_upgrade.md#flag-image |
| An option | its page, mkimages.md, image-options.md or extension-api.md, and its name in lower case, keeping only letters, digits, - and _, with <name> and * dropped: mkimages.md#imagesmodules, image-options.md#chalkosdiskespsize |
| An API method, message or enum | method-, message- or enum- and the name in lower case without dots: api.md#method-upgrade |
| A kind | its name in lower case: kinds.md#systemdisk |
| A built-in | builtins.md# and rules- and a kind in lower case, or fact-, output- or effect- and the name: builtins.md#rules-volume, builtins.md#effect-networkd |
Checks¶
Two flake checks guard the documentation:
| Check | Fails when |
|---|---|
docs |
The navigation names a page that does not exist; the strict build finds a broken link or anchor; docgen check finds a command that does not exist; docgen yaml finds a config document the schemas refuse; a Nix block a page shows does not parse; or docgen packages finds a directory of Go code in cmd/ or pkg/ without a row in contribute/packages.md, or a row there for a directory without Go code. |
docs-generated |
The generated pages in the repository differ from what the code generates. It names nix run .#docgen as the fix. |
Run both before handing in a change:
docgen check reads every fenced block in sh, bash, shell, zsh, console,
shell-session or without a language. It strips $ prompts, joins lines ending in \,
follows wrappers such as sudo, env, nix run .#chalklab -- and nix develop -c, and
reports a chalkctl, chalklab, chalkbuild or chalkcfg command, subcommand or flag that
does not exist, a single-dash long flag and a flag missing its value. Positional arguments and
flag values are not checked, so placeholders such as <node> pass. For a page whose block runs
chalkctl upgrade with a --dry-run flag and chalkctl status with -insecure, it reports:
docgen: commands in the documentation that chalkctl, chalklab, chalkbuild and chalkcfg do not have:
docs/operate/example.md:8: chalkctl upgrade --config lab.json --dry-run: chalkctl upgrade has no flag --dry-run
docs/operate/example.md:9: chalkctl status cp1 -insecure: chalkctl status has no flag -i
Commands shown in prose or in a text block are not checked, so show commands in shell blocks.
To run the check alone, from the repository's root:
docgen yaml reads every yaml block and checks each document whose group is chalkos.dev, a
subdomain of it, or the group of a kind the examples declare, such as rack.example.org or
bgp.example.org, as chalkctl validate checks a node's files: against the schemas of an
image with the Kubernetes layer and the examples' kinds, and of the inventory and the lab file. A
kind the image does not declare, a misspelled field or a value of the wrong type fails, and the
error names the page's line the document starts on. Documents of other groups, such as Kubernetes
objects, fragments without an apiVersion and documents that are not objects are not checked.
The docs check also runs nixfmt's parser over every nix block. A block whose title names a
.nix file is a whole file and must parse as one. A block without such a title is a fragment and
must parse as an expression, or within braces as the attributes of a module, such as
chalkos.kernel.moduleGroups = [ "gpu" ];. Both checks run only in the docs check, which
builds the image's schemas and provides nixfmt.
Add a page¶
- Create the Markdown file in its section's directory, starting with front matter of a
titleand adescriptionand an H1 equal to the title, as the docs style guide shows. - Write it from the template of its kind in the docs style guide.
- Add it to its group in the navigation in
zensical.toml, outside the generated region, and under the same group's heading on its section's index page. git addit, then run thedocscheck.
Publishing¶
The workflow .github/workflows/docs.yml builds .#docs on every push to main and deploys
the result to GitHub Pages, at https://trevex.github.io/chalkos/. It runs no other check, so a
change is checked locally before it is merged. The documentation is not versioned: the site
describes main.