Build documentation

The book is mdBook, built from docs/. Parts of it are generated from the code, and every code block in it is checked.

python3 scripts/docs/build_single_version_docs.py preview
python3 scripts/docs/rebuild_index.py
python3 -m http.server 8000 --directory book

Open http://localhost:8000 for the landing page and the book. Install the prerequisites first:

cargo install mdbook --version 0.5.2 --locked
python3 -m pip install -r scripts/requirements.txt

The scripts find mdBook on PATH or in ~/.cargo/bin/.

Where to edit

Style

A moved page or heading gets a redirect in book.toml, and the README and landing page links move in the same change.

Generated pages

Do not edit these by hand. Change the code they come from, then write them:

cargo run -p datui-cli --bin gen_docs -- write

GENERATED in crates/datui-cli/src/docgen.rs lists them. A region sits between two comments, which mdBook and GitHub hide; the text around it is written by hand:

<!-- generated: keys -->
<!-- end generated: keys -->

In the landing page the comments are Jinja’s, {# generated: NAME #}; in TOML, Ruby and desktop files, # generated: NAME.

the_generated_docs_are_current (scripts/dev/test.sh cli) fails while a committed copy differs. gen_docs with no argument prints the command-line reference; with settings, environment or keys, that page.

Code blocks

Every fenced block in docs/, the READMEs and the next release’s notes is one of three kinds, named in its info string. On the landing page every <pre> names it in data-example (<pre data-example="bash,network">), and the runner checks and runs those the same way:

Code shown from the source (rust, yaml, json) is not run. More attributes go after the language, comma-separated:

A runnable block stands alone: it uses the built-in catalog’s public data, real commands (seq, printf, journalctl), or the file blocks above it. Files an example needs are titled file blocks, never heredocs; sample-data generators are readable scripts. Each file is its own block, its name in bold on the line above, and the command block runs it by name:

**`make_day_l2.py`**

```python,file=make_day_l2.py
...
```

```bash
python3 make_day_l2.py
datui day.l2
```

The lint fails a heredoc or a python -c in a shell block, and a file block the next runnable block does not name. A binary generator lays out its records with ctypes.LittleEndianStructure (_pack_ = 1, _layout_ = "ms"), a field per field of the format. A bash or toml block never starts a line with a # comment; say it in the text, or at the end of a command.

The examples datui --help, the manpages and the command-line reference show are crates/datui-cli/examples.toml: each entry’s command, description, test (run, network or interactive), an optional expect, and the pages whose EXAMPLES show it (datui.1 when not given; datui COMMAND --help shows those of datui-COMMAND.1). Every command page needs one. Files a command reads are a files list ([{ name, text }]): the runner writes them and the pages show each under its name, never a printf into a file. Each runs with HOME set to its own directory, so an example may install into ~.

Run the checks

A shell block runs in an empty directory with its own DATUI_CONFIG_DIR and DATUI_CACHE_DIR. scripts/docs/datui_shim.py stands in for the reader: it runs datui on a pseudo-terminal, passes once the table shows rows, answers a download question, and otherwise fails with the screen’s last text. A failure names the file and line.

The queries on public data run once the datasets are downloaded:

.venv/bin/python scripts/docs/doc_examples.py --fetch-datasets ~/tmp/doc-data
DATUI_DOC_DATA=~/tmp/doc-data cargo test -p datui-lib --lib doc_queries -- --ignored

CI runs the lints and the local blocks on every pull request. Nightly runs the network blocks, the network Python blocks and the queries on public data. Check the examples covers the numbers the guides quote.

Build choices

A branch build writes the command-line reference into a temporary copy; a tag build uses the one committed with the tag. The landing page lists release and development books. It stays a landing page; it does not redirect into a book. Check it in light and dark, at phone and desktop widths, with the keyboard and with JavaScript off.

Publishing

A deploy replaces the whole site, so both workflows build every tag (from cache), /latest/ and /dev/. A merged docs change shows at /dev/ within minutes and reaches /latest/ with the next release. Build and publish docs can also be run by hand. A tag’s cached book is marked by book/<tag>/.built_sha; remove the marker to rebuild it locally.