-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
Showing
1 changed file
with
27 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |