From 962bb5d038d412e198785580a3a24a655d4770f0 Mon Sep 17 00:00:00 2001
From: Conor Schaefer <conor@ruin.dev>
Date: Tue, 23 Jul 2024 17:08:47 -0700
Subject: [PATCH] fix: update docs build in dev guide

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.
---
 pages/dev/docs.md | 45 +++++++++++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/pages/dev/docs.md b/pages/dev/docs.md
index 29e7d23..d8767d8 100644
--- a/pages/dev/docs.md
+++ b/pages/dev/docs.md
@@ -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