Contributing#

Changes come as pull requests to stackhands/eb-pipeline. A change to behaviour changes the page that describes it in the same pull request.

Record the change#

Every change adds a news fragment, changelog.d/+SLUG.TYPE.md, with a short slug for the change and one of the types towncrier.toml configures:

Type

Section of the release notes

feature

Features

bugfix

Fixes

doc

Documentation

removal

Removals

misc

Miscellaneous

A fragment is one paragraph in the present tense that names the commands, options, keys and files it is about in backticks. With towncrier 26.9.0 installed, towncrier build --draft --version 0.3.0 prints the release notes the fragments make. CI runs the same draft, and fails on a fragment whose name has no type. A release writes the fragments into CHANGELOG.md, as RELEASING.md describes.

Run the tests#

With Rust 1.90 or newer, from the top of the repository:

cargo fmt --all --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked

tests/run_stubs.rs runs eb-pipeline run against stub programs for eb, eb-stack, eb-keep-logs and eb-staged-rebuild, written into a temporary directory. tests/examples.rs checks that the built-in templates hold placeholders only. Set EB_PIPELINE_LINT_DENY to a comma-separated list of your own site’s names or paths before cargo test --locked --test examples to refuse them in the templates as well; the repository names none. CI also builds with Rust 1.90.0, the oldest Rust the crate supports, with cargo build --locked --all-targets.

The scripts under docs/examples/ run the commands the pages show, in order, against the eb-pipeline that cargo build --locked built, and stop when an exit status or a line that a page explains is not what the page says:

cargo build --locked
bash docs/examples/tutorial.sh

The docs job of the ci workflow runs every one of them but install.sh, which downloads release 0.3.0 and builds a clone of the checkout with cargo install. Run that one by hand when the install steps change, with a Rust toolchain of 1.90 or newer, as RUSTUP_TOOLCHAIN=1.90.0 bash docs/examples/install.sh.

Build the documentation#

The documentation toolchain is pinned in pixi.lock: Emacs, Sphinx, lychee, and the Rust 1.90 that builds the API pages. With pixi installed, from the top of the repository:

pixi run -e docs docbld

The site is in docs/build/html/; open docs/build/html/index.html. The build fails on any Sphinx warning, any cross-reference that does not resolve, any rustdoc warning, any public item of the library without a doc comment, any internal link or anchor that does not exist, and, outside the changelog, any name of a real site’s machines or paths. It also fails when docs/export.el writes the code or verbatim text of a test page as a different literal, such as \*.log for *.log. The first build needs the network, to fetch the other stackhands sites’ inventories; later builds reuse them for 30 days.

External links are checked separately, as they need the network:

pixi run -e docs linkcheck

pixi run -e docs docdel removes everything the build generated.

Where things are#

Path

What it holds

docs/orgmode/

the pages, in Org: edit these

docs/export.el

the Org to reStructuredText export

docs/source/conf.py

the Sphinx configuration

docs/source/_ext/

the documentation template’s Sphinx domain for Zig, unused here

docs/tools/check_site.py

checks internal links, anchors and forbidden names

docs/tools/test_export.py

checks the literals that docs/export.el writes

docs/tools/api-index.html

the front page of the rustdoc site, which cargo doc does not write

docs/examples/

the scripts that print the output the pages show

The .rst files under docs/source/ and everything under docs/build/ are generated and not committed. pixi run -e docs rustdoc runs cargo doc into docs/build/cargo/ and copies the result to docs/build/html/api/.

Write a page#

A page belongs to exactly one quadrant: a tutorial teaches by doing, a how-to guide gets one task done, an explanation says why, and a reference page lists what there is. Start from the skeleton for its quadrant in docs-kit/skeletons/ of stackhands/.github, add it to the toctree of the quadrant’s index.org, and follow docs-kit/STYLE.md there. Examples use the neutral example site (example.org, /opt/site, /home/alice), never a real one.

Every command and output block comes from a real run. A page that shows output has a script under docs/examples/ that runs its commands and prints what they print, with its temporary directories written as $WORK and $HOME; paste the output from there. A file of more than a few lines that a page shows lives beside the page, as docs/orgmode/tutorials/first-build-list/site.sh does, and the page pulls it in with #+INCLUDE, so that the script runs the file the page shows.

API documentation is written in the code, and the first sentence of each comment is the summary shown in lists. In Rust it is a /// comment above each pub item and a //! comment at the top of each module. A site file key is documented once, in the doc_struct! table of src/schema.rs: that text is both what eb-pipeline schema prints and the doc comment of the key’s field. The site file lists the same keys, and tests/docs.rs fails when one of its tables and the schema differ in a key, its order, its type or its default.