Metropolis Handbook

This directory contains the sources of the Metropolis Handbook end-user documentation.

Layout

Everything within //monogon/handbook/src will be used to generate documentation with mdbook.

Compared to upstream mdbook we do not have a static book.toml file, one is instead generated as part of the build process. See the definition of the //metropolis/handbook target to change some of the options.

Building

bazel build //metropolis/handbook

Then, you can visit the following file in your browser:

bazel-bin/metropolis/handbook/handbook/index.html

To view the built documentation.

Interactive editing

For faster edit/check loops of the handbook, you can use ibazel:

ibazel build //metropolis/handbook

This will automatically rebuild the handbook any time some source changes.

You will still need to manually refresh your browser to see any changes. This could be made better, if needed, by injecting some ibazel-compatible live reload javascript to automatically reload the page on changes, or by adding a target which launches mdbook serve.

Publishing

We currently do not build the handbook automatically and/or publish it anywhere.