We are very happy to recieve documentation pull-requests.
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.
Building and testing
To build the API documentation locally, run:
# Build doc for all modules: cargo doc --all --no-deps # And open it: xdg-open target/doc/rand/index.html
On Linux, it is easy to set up automatic rebuilds after any edit:
while inotifywait -r -e close_write src/ rand_core/; do cargo doc; done
After editing API documentation, we reccomend testing examples and checking for broken links:
cargo test --doc cargo install cargo-deadlinks # It is recommended to remove left-over files from previous compilations rm -rf /target/doc cargo doc --all --no-deps cargo deadlinks --dir target/doc
The book is built using mdbook, which makes building and testing easy:
cargo install mdbook --version "^0.2" 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