Documentation

Style

All documentation is in English, but no particular dialect is preferred.

The documentation should be accessible to multiple audiences: both seasoned Rustaceans and relative newcomers, those with experience in statistical modelling or cryptography, as well as those new to the subjects. Since it is often impossible to write appropriate one-size-fits-all documentation, we prefer concise technical documentation with reference to extended articles aimed at more specific audiences.

API documentation

Rand crates

It is recommended to use nightly Rust for correct link handling.

To build all API documentation for all crates in the rust-random/rand repository, run:

# Optionally, enable some unstable but widely used doc features:
export RUSTDOCFLAGS="--cfg docsrs -Zunstable-options --generate-link-to-definition"

# Build doc for all crates in the workspace:
cargo doc --workspace --no-deps --all-features --open

(Alternatively, check the Cargo.toml under [package.metadata.docs.rs] which may suggest workspace- or crate-specific configuration.)

On Linux, it is easy to set up automatic rebuilds after any edit:

while inotifywait -r -e close_write src/ rand_*/; do cargo doc; done

After editing API documentation, we recommend testing examples:

cargo test --doc

Getrandom crate

The rust-random/getrandom repository contains only a single crate, hence a simple cargo doc will suffice.

Auxiliary documentation

README files

README files contain a brief introduction to the crate, shield badges, useful links, feature-flag documentation, licence information, and potentially an example.

For the most part these files do not have any continuous testing. Where examples are included (currently only for the rand_jitter crate), we enable continuous testing via doc_comment (see lib.rs:62 onwards).

CHANGELOG files

Changelog formats are based on the Keep a Changelog format.

All significant changes merged since the last release should be listed under an [Unreleased] section at the top of log.

The book

The source to this book is contained in the rust-random/book repository. It is built using mdbook, which makes building and testing easy:

cargo install mdbook --version "^0.4"

mdbook build --open
mdbook test

# To automatically rebuild after any changes:
mdbook watch

Note that links in the book are relative and designed to work in the published book. If you build the book locally, you might want to set up a symbolic link pointing to your build of the API documentation:

ln -s ../rand/target/doc rand