doctest

Overview ¶

Command doctest runs the examples in docsync's guide pages against the built ds binary and fails when what a page shows is not what ds prints.

Why it exists: every unit test here asserts what its author expected, on inputs the author chose, through the parts the author wired up. Writing the guide -- running every documented behaviour as a user would, with the page as the oracle -- found some eighty places where the binary and its own documentation disagreed, after 400 e2e cases and 100% statement coverage had found none of them. This keeps that check permanent: a page whose example no longer matches the binary fails the gate, so the guide cannot drift from the tool and the tool cannot regress behind the guide.

A page is run top to bottom in one fresh git repository:

• A fenced block whose info string carries file=PATH is written to PATH (relative to the current directory) before the next command runs. file=PATH append=true appends instead.
• A fenced block whose first line starts with "$ " is a session: each "$ " line is a command, the lines after it until the next command are its expected output. A command ending in a heredoc (<<'EOF') takes the following lines up to the terminator as its input, not as output.
• <!-- doctest ... --> holds hidden commands, run but not compared: the setup a reader does not need to see (git commits, a fake plugin).
• <!-- doctest:skip REASON --> before a block skips it. The reason is printed and the skip counted, so a page cannot pass by skipping.

Ids are minted at random, so the id a page shows is not the id ds mints when the page runs. Once an id is paired (below), every later command and file the page writes has the page's id replaced by the real one: a page can `$ ds def x.go#F`, then `$ ds ack <the id it showed>` and cite it in a doc, and the run uses the id ds actually minted.

`$ cd DIR` and `$ export K=V` change the directory and environment of the commands after them. Expected output may contain a line that is only "…" (any number of lines) or end a line with "…" (any rest of the line). Generated values are normalised on both sides before comparing: commit hashes, block hashes, timestamps, dates, durations and the repository's temporary path. Id suffixes are paired instead: where the page shows an id and ds printed one in the same place, the two are paired for the rest of the page, one to one, so the same id must recur where the page says it does. Lines an ellipsis skips pair nothing.