Building documentation

Penumbra guide

The guide (opens in a new tab) (i.e. this document) is build using Nextra (opens in a new tab), and the source config lives in the guide repo (opens in a new tab). See that repo's README for setup instructions.

Protocol docs

The protocol docs (opens in a new tab) are maintained in the protocol repo (opens in a new tab), and are built using mdBook (opens in a new tab). To build locally, set up the dev env, then run:

cd docs/protocol
mdbook serve

Rust API docs

The Rust API docs (opens in a new tab) are maintained in the protocol repo (opens in a new tab), and can be built with ./deployments/scripts/rust-docs. Notably, the rust docs require the use of a nightly rust toolchain, which isn't currently provided via the dev env. You should install the nightly toolchain on your host machine, if you need to build the rustdocs locally.

The landing page, the top-level index.html, is handled as a special case. If you added new crates by appending a -p <crate_name> to the rust-docs script, then you must rebuild the index page by running the custom script.

Static site hosting

All the documentation sites listed above use Firebase (opens in a new tab) for static web hosting. To debug Firebase-specific functionality like redirects, use firebase emulators:start to run a local webserver. You'll need to rebuild the docs with the appropriate tooling to get livereload functionality, however, e.g. mdbook serve or pnpm dev, depending on the site.