From 7854a5fc561e2e3f514421c3ea97c80cea5a673e Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Wed, 17 Apr 2024 16:56:28 -0700 Subject: [PATCH] docs(guide): simplify url routes Modifies the firebase hosting config to remove the `//` prefix from the guide URLs, which has only ever been `/main/`, due to #6. Also includes rewrites so that historical URLs with the `/main/` prefix will still be honored, and redirected to the appropriate location that's live in the docs. Squirreling away this one-liner for generating a "sitemap" of all URLs: curl -s http://localhost:5000 \ | rg -i 'class="chapter"' \ | perl -npE 's/href=/\nhref=/g ' \ | perl -nE '/href="([\w.\/]+)"/g and say $1' > sitemap.txt which was helpful in creating the redirects. Removes the mdboook-only meta-refresh redirects added in #4232, because the browser UX was atrocious. Refs #3417. --- .github/workflows/notes.yml | 12 ++---------- .gitignore | 10 +++++----- docs/guide/.firebaserc | 5 +++++ docs/guide/book.toml | 14 -------------- docs/guide/firebase.json | 28 +++++++++++++++++++--------- docs/guide/src/dev/docs.md | 11 +++++++++-- 6 files changed, 40 insertions(+), 40 deletions(-) create mode 100644 docs/guide/.firebaserc diff --git a/.github/workflows/notes.yml b/.github/workflows/notes.yml index d6f3de83e3..504cbd5c97 100644 --- a/.github/workflows/notes.yml +++ b/.github/workflows/notes.yml @@ -36,15 +36,8 @@ jobs: run: cargo +nightly install mdbook mdbook-katex mdbook-mermaid mdbook-linkcheck - name: Build software guide - run: cd docs/guide && mdbook build - - - name: Move software guide to subdirectory - run: | - cd docs/guide - rm -rf firebase-tmp - mkdir firebase-tmp - mv book/html firebase-tmp/${{ github.event.inputs.image_tag || github.ref_name }} - tree firebase-tmp + working-directory: docs/guide + run: mdbook build - name: Deploy software guide to firebase uses: w9jds/firebase-action@v12.9.0 @@ -52,7 +45,6 @@ jobs: args: deploy env: FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }} - PROJECT_ID: penumbra-guide PROJECT_PATH: docs/guide - name: Build protocol spec diff --git a/.gitignore b/.gitignore index b827c025af..0ea14d1815 100644 --- a/.gitignore +++ b/.gitignore @@ -5,12 +5,12 @@ wallet-next/pwalletd-db.sqlite-wal *.DS_STORE -book +# mdbook docs builds +docs/*/book/* +# firebase config .firebase/ -# For some reason mdbook dumps this here because the main page is ../README.md -#index.html -# Used for deployments -firebase-tmp/ +firebase-debug.log +docs/*/firebase-tmp/ # Nix build output goes here result diff --git a/docs/guide/.firebaserc b/docs/guide/.firebaserc new file mode 100644 index 0000000000..431e9a65a9 --- /dev/null +++ b/docs/guide/.firebaserc @@ -0,0 +1,5 @@ +{ + "projects": { + "default": "penumbra-guide" + } +} diff --git a/docs/guide/book.toml b/docs/guide/book.toml index 32fd9218c3..c443142e63 100644 --- a/docs/guide/book.toml +++ b/docs/guide/book.toml @@ -27,17 +27,3 @@ warning-policy = "error" # The buf.build website doesn't support HTTP HEAD calls, returning 405. # Only relevant when `follow-web-links=true`. exclude = ['buf\.build'] - -[output.html.redirect] -# Renames in GH4215. -"pd.html" = "node/pd.html" -"pd/chain-upgrade.html" = "node/pd/chain-upgrade.html" -"pd/debugging.html" = "node/pd/debugging.html" -"pd/install.html" = "node/pd/install.html" -"pd/join-testnet.html" = "node/pd/join-testnet.html" -"pd/requirements.html" = "node/pd/requirements.html" -"pd/validator.html" = "node/pd/validator.html" -"pclientd.html" = "node/pclientd.html" -"pclientd/build_transaction.html" = "node/pclientd/build_transaction.html" -"pclientd/configure.html" = "node/pclientd/configure.html" -"pclientd/rpc.html" = "node/pclientd/rpc.html" diff --git a/docs/guide/firebase.json b/docs/guide/firebase.json index fc8584c8f0..988c695f93 100644 --- a/docs/guide/firebase.json +++ b/docs/guide/firebase.json @@ -1,16 +1,26 @@ { "hosting": { - "public": "firebase-tmp", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], + "public": "book/html", "redirects": [ { - "source": "/", - "destination": "/main/index.html", - "type": 301 + "source": "/main/index.html", + "destination": "/", + "type": 302 + }, + { + "regex": "/main/pd(?P.*)", + "destination": "/node/pd:page", + "type": 302 + }, + { + "regex": "/main/pclientd(?P.*)", + "destination": "/node/pclientd:page", + "type": 302 + }, + { + "regex": "/main/(?P.*)", + "destination": "/:page", + "type": 302 } ] } diff --git a/docs/guide/src/dev/docs.md b/docs/guide/src/dev/docs.md index e92ff5cb18..573d2fc840 100644 --- a/docs/guide/src/dev/docs.md +++ b/docs/guide/src/dev/docs.md @@ -1,11 +1,17 @@ # Building documentation +## mdBook docs The [protocol docs] and the [guide] (this document) are built using -[mdBook] and auto-deployed on pushes to `main`. To build locally: +[mdBook] and auto-deployed on pushes to `main`. To build locally: -1. Install the requirements: `cargo install mdbook mdbook-katex mdbook-mermaid` +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). +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. + +## Rust API docs The [Rust API docs][rustdoc] can be built with `./deployments/scripts/rust-docs`. The landing page, the top-level `index.html`, is handled as a special case. If you added new crates by appending a `-p ` to the `rust-docs` script, @@ -24,3 +30,4 @@ CI will automatically rebuild all our docs on merges into main. [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