From e06357f795d78161c5f90e80849bbb2786f3b14c Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 17 Jul 2020 20:15:50 -0700 Subject: [PATCH] Add skeleton of eventual zebra book (#653) * Add skeleton of eventual zebra book * reorg sections * restore file and reorg book a little * try setting up a firebase deployment * allow firebase ci to work on test * download mdbook * fix book path * use newer version of mdbook * remove event hook for book branch pre merge * Apply suggestions from code review Co-authored-by: Henry de Valence Co-authored-by: Henry de Valence --- .github/workflows/firebase.yml | 27 +++++++++++++++++- book/.gitignore | 1 + book/book.toml | 6 ++++ book/firebase.json | 16 +++++++++++ book/src/CONTRIBUTING.md | 18 ++++++++++++ book/src/SUMMARY.md | 15 ++++++++++ book/src/design_docs.md | 1 + {design => book/src/designs}/0000-template.md | 0 .../designs/0001-pipelinable-block-lookup.md | 0 book/src/diagrams.md | 1 + .../src/diagrams/zebra-network.md | 4 ++- .../src/diagrams}/zebra-network.monopic | Bin book/src/introduction.md | 11 +++++++ {design => book/src}/overview.md | 2 +- 14 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 book/.gitignore create mode 100644 book/book.toml create mode 100644 book/firebase.json create mode 100644 book/src/CONTRIBUTING.md create mode 100644 book/src/SUMMARY.md create mode 100644 book/src/design_docs.md rename {design => book/src/designs}/0000-template.md (100%) rename {design => book/src}/designs/0001-pipelinable-block-lookup.md (100%) create mode 100644 book/src/diagrams.md rename design/zebra-network.txt => book/src/diagrams/zebra-network.md (99%) rename {design => book/src/diagrams}/zebra-network.monopic (100%) create mode 100644 book/src/introduction.md rename {design => book/src}/overview.md (99%) diff --git a/.github/workflows/firebase.yml b/.github/workflows/firebase.yml index 6f257ac5..36f59738 100644 --- a/.github/workflows/firebase.yml +++ b/.github/workflows/firebase.yml @@ -11,16 +11,39 @@ jobs: name: Build and Deploy Docs runs-on: ubuntu-latest steps: + - name: Checkout the source code + uses: actions/checkout@master - - uses: actions/checkout@master - name: Install latest nightly uses: actions-rs/toolchain@v1 with: toolchain: nightly override: true + + - name: Install mdbook + run: | + cd book + curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.1/mdbook-v0.4.1-x86_64-unknown-linux-gnu.tar.gz | tar xz + # Add the book directory to the $PATH + echo "::add-path::$GITHUB_WORKSPACE/book" + + - name: Build Zebra book + run: | + mdbook build book/ + + - name: Deploy Zebra book to firebase + uses: w9jds/firebase-action@v1.5.0 + with: + args: deploy + env: + FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }} + PROJECT_PATH: book/ + PROJECT_ID: zebra-book + - name: Build external docs run: | cargo doc --no-deps + - name: Deploy external docs to firebase uses: w9jds/firebase-action@v1.5.0 with: @@ -28,9 +51,11 @@ jobs: env: FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }} PROJECT_ID: zealous-zebra + - name: Build internal docs run: | cargo doc --no-deps --document-private-items + - name: Deploy external docs to firebase uses: w9jds/firebase-action@v1.5.0 with: diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 00000000..7585238e --- /dev/null +++ b/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 00000000..f726c892 --- /dev/null +++ b/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Zcash Foundation "] +language = "en" +multilingual = false +src = "src" +title = "The Zebra Book" diff --git a/book/firebase.json b/book/firebase.json new file mode 100644 index 00000000..6fe0e74e --- /dev/null +++ b/book/firebase.json @@ -0,0 +1,16 @@ +{ + "hosting": { + "public": "book", + "ignore": [ + "firebase.json", + "**/.*", + "**/node_modules/**" + ], + "rewrites": [ + { + "source": "**", + "destination": "/index.html" + } + ] + } +} \ No newline at end of file diff --git a/book/src/CONTRIBUTING.md b/book/src/CONTRIBUTING.md new file mode 100644 index 00000000..4e5d408e --- /dev/null +++ b/book/src/CONTRIBUTING.md @@ -0,0 +1,18 @@ +# Contributing + +* [Bug Reports](#bug-reports) +* [Running and Debugging](#running-and-debugging) +* [Pull Requests](#pull-requests) +* [Writing Documentation](#writing-documentation) + +## Bug Reports +[bug-reports]: #bug-reports + +## Running and Debugging +[running-and-debugging]: #running-and-debugging + +## Pull Requests +[pull-requests]: #pull-requests + +## Writing Documentation +[writing-documentation]: #writing-documentation diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 00000000..9a41e5d1 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,15 @@ +# Summary + +[Introduction](./introduction.md) +[Contribution Guide](./CONTRIBUTING.md) +[Design Overview](./overview.md) + +# Diagrams + +- [Diagrams](./diagrams.md) + - [Zebra Network](./diagrams/zebra-network.md) + +# Designs + +- [Design Documents](design_docs.md) + - [Pipelinable Block Lookup](./designs/0001-pipelinable-block-lookup.md) diff --git a/book/src/design_docs.md b/book/src/design_docs.md new file mode 100644 index 00000000..b24598c0 --- /dev/null +++ b/book/src/design_docs.md @@ -0,0 +1 @@ +# Design Documents diff --git a/design/0000-template.md b/book/src/designs/0000-template.md similarity index 100% rename from design/0000-template.md rename to book/src/designs/0000-template.md diff --git a/design/designs/0001-pipelinable-block-lookup.md b/book/src/designs/0001-pipelinable-block-lookup.md similarity index 100% rename from design/designs/0001-pipelinable-block-lookup.md rename to book/src/designs/0001-pipelinable-block-lookup.md diff --git a/book/src/diagrams.md b/book/src/diagrams.md new file mode 100644 index 00000000..612e7c0c --- /dev/null +++ b/book/src/diagrams.md @@ -0,0 +1 @@ +# Diagrams diff --git a/design/zebra-network.txt b/book/src/diagrams/zebra-network.md similarity index 99% rename from design/zebra-network.txt rename to book/src/diagrams/zebra-network.md index d202710a..94da84d6 100644 --- a/design/zebra-network.txt +++ b/book/src/diagrams/zebra-network.md @@ -1,3 +1,4 @@ +``` ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │PeerServer │ │PeerServer │ │PeerServer │ │PeerServer │ │ ┌───────┐ │ │ ┌───────┐ │ │ ┌───────┐ │ │ ┌───────┐ │ @@ -74,4 +75,5 @@ │ when internal │ │ services are │ │ overloaded │ - └───────────────┘ \ No newline at end of file + └───────────────┘ +``` \ No newline at end of file diff --git a/design/zebra-network.monopic b/book/src/diagrams/zebra-network.monopic similarity index 100% rename from design/zebra-network.monopic rename to book/src/diagrams/zebra-network.monopic diff --git a/book/src/introduction.md b/book/src/introduction.md new file mode 100644 index 00000000..0c8621f9 --- /dev/null +++ b/book/src/introduction.md @@ -0,0 +1,11 @@ +# The Zebra Book + +Introduce the zebra project, explain what its for, high level concepts, how it differs from zcash, why it's being written. + +# Dev Guide + +Link to various chapters about how to contribute or work with the project, how to manipulate the log levels, how to set up the project, and the various dev practices we follow. + +# Design + +Introduce the overview and design documents. document how to propose a new design. \ No newline at end of file diff --git a/design/overview.md b/book/src/overview.md similarity index 99% rename from design/overview.md rename to book/src/overview.md index cfb5b5b0..3e37954a 100644 --- a/design/overview.md +++ b/book/src/overview.md @@ -1,5 +1,5 @@ Zebra Design Document -===================== +--------------------- This document sketches the future design for Zebra.