Skip to content

Commit

Permalink
fix: update docs build in dev guide
Browse files Browse the repository at this point in the history
Now that we've broken out the guide into its own repo, we need to be
clearer about where the various docs static sites should be edited.
  • Loading branch information
conorsch committed Jul 24, 2024
1 parent 6fbe5fd commit 962bb5d
Showing 1 changed file with 27 additions and 18 deletions.
45 changes: 27 additions & 18 deletions pages/dev/docs.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,40 @@
## mdBook docs
The [protocol docs] and the [guide] (this document) are built using
[mdBook] and auto-deployed on pushes to `main`. To build locally:
## Penumbra guide
The [guide] (i.e. this document) is build using [Nextra],
and the source config lives in the [guide repo]. See that repo's README
for setup instructions.

1. Install the requirements: `cargo install mdbook mdbook-katex mdbook-mermaid mdbook-linkcheck`
2. Run `mdbook serve` from `docs/protocol` (for the protocol spec) or from `docs/guide` (for this document).
## Protocol docs
The [protocol docs] are maintained in the [protocol repo], and are built using [mdBook].
To build locally, [set up the dev env](dev-env.mdx), then run:

The hosting config uses [Firebase]. To debug Firebase-specific functionality like redirects,
use `firebase emulators:start` to run a local webserver. You'll need to rebuild the docs
with `mdbook build` to get livereload functionality, however.
```shell
cd docs/protocol
mdbook serve
```

## Rust API docs
The [Rust API docs][rustdoc] can be built with `./deployments/scripts/rust-docs`.
The [Rust API docs][rustdoc] are maintained in the [protocol repo], 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](dev-env.md). 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 via:

You'll need to use the `nightly` toolchain for Rust to build the docs. In some cases, you'll need
a specific version. To configure locally:
then you must rebuild the index page by running the custom script.

```
rustup toolchain install nightly-2023-05-15
```

CI will automatically rebuild all our docs on merges into main.
## Static site hosting
All the documentation sites listed above use [Firebase] 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.

[protocol docs]: https://protocol.penumbra.zone
[protocol repo]: https://github.com/penumbra-zone/penumbra
[rustdoc]: https://rustdoc.penumbra.zone
[guide]: https://guide.penumbra.zone
[mdBook]: https://rust-lang.github.io/mdBook/
[Firebase]: https://firebase.google.com/docs/functions/local-emulator#install_the_firebase_cli
[Nextra]: https://nextra.site
[guide repo]: https://github.com/penumbra-zone/guide

0 comments on commit 962bb5d

Please sign in to comment.