Documentation

This chapter describes how the GWR engine and accompanying libraries are documented.

Developer Guide

The developer guide is an mdbook. In order to produce the document it is necessary to first install the development dependencies by running:

./.github/actions/install-dev-dependencies/install.sh

and then build and open the user guide with:

cd gwr-developer-guide/
mdbook build --open

If developing the guide then this command will launch a process that continually monitors the source and regenerates the HTML if it changes (causing the browser to automatically refresh):

mdbook serve --open

This user guide is written using mdbook. However, because these packages are not released via crates.io the usual Rust playground integration is disabled.

As use of the mdbook test command does not lend itself well to testing crates directly from a local workspace all Rust source within the developer guide is instead tested using the mdBook-Keeper plugin. This plugin tests all included code snippets during the mdBook build process.

A “wrapper” test within the Rust source of the gwr_developer_guide library is used to ensure that the mdBook build process is tested whenever cargo test is run at the workspace level.

API Documentation

Documentation within the GWR source is done using rustdoc formatting such that APIs are documented and any code snippets are compiled and run.

This documentation can be generated by running:

cargo doc-gwr --open

The documentation can also be generated to include private items, which can be useful when developing GWR packages, by running:

cargo doc-gwr-dev --open

Building this developer guide also generates the API documentation.