From 667cec7804eafdcb26e58c7a1dc4b7a3c167dac0 Mon Sep 17 00:00:00 2001 From: Matthew Sevey Date: Wed, 20 Sep 2023 16:52:54 -0400 Subject: [PATCH] feat: init mdbooks for specs site with place holder files (#1199) ## Overview This PR adds [mdbook](https://rust-lang.github.io/mdBook/guide/installation.html) for hosting the specs site. A workflow was added to deploy the specs site to github pages. ## Checklist - [ ] New and updated code has appropriate documentation - [ ] New and updated code has new and/or updated testing - [ ] Required CI checks are passing - [ ] Visual proof for any user facing features like CLI or documentation updates - [ ] Linked issues closed with keywords --------- Co-authored-by: nashqueue <99758629+nashqueue@users.noreply.github.com> --- .github/workflows/specs-deploy.yml | 47 ++++++++++++++++++++++++++++++ .gitignore | 1 + block/block.md | 1 + da/da.md | 1 + mempool/mempool.md | 1 + node/node.md | 1 + p2p/p2p.md | 1 + specs/.gitignore | 1 + specs/README.md | 38 ++++++++++++++++++++++++ specs/book.toml | 16 ++++++++++ specs/src/README.md | 3 ++ specs/src/SUMMARY.md | 12 ++++++++ specs/src/specs/block.md | 1 + specs/src/specs/da.md | 1 + specs/src/specs/mempool.md | 1 + specs/src/specs/node.md | 1 + specs/src/specs/p2p.md | 1 + specs/src/specs/state.md | 1 + specs/src/specs/store.md | 1 + specs/src/specs/template.md | 1 + specs/template.md | 37 +++++++++++++++++++++++ state/state.md | 1 + store/store.md | 1 + 23 files changed, 170 insertions(+) create mode 100644 .github/workflows/specs-deploy.yml create mode 100644 block/block.md create mode 100644 da/da.md create mode 100644 mempool/mempool.md create mode 100644 node/node.md create mode 100644 p2p/p2p.md create mode 100644 specs/.gitignore create mode 100644 specs/README.md create mode 100644 specs/book.toml create mode 100644 specs/src/README.md create mode 100644 specs/src/SUMMARY.md create mode 120000 specs/src/specs/block.md create mode 120000 specs/src/specs/da.md create mode 120000 specs/src/specs/mempool.md create mode 120000 specs/src/specs/node.md create mode 120000 specs/src/specs/p2p.md create mode 120000 specs/src/specs/state.md create mode 120000 specs/src/specs/store.md create mode 120000 specs/src/specs/template.md create mode 100644 specs/template.md create mode 100644 state/state.md create mode 100644 store/store.md diff --git a/.github/workflows/specs-deploy.yml b/.github/workflows/specs-deploy.yml new file mode 100644 index 00000000000..ab0ab5ff492 --- /dev/null +++ b/.github/workflows/specs-deploy.yml @@ -0,0 +1,47 @@ +name: Specs Deploy + +on: + push: + branches: + - main + paths: + - specs/** + pull_request: + paths: + - specs/** + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@v4 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: "0.4.21" + + - name: Build book + run: mdbook build specs + + - name: Deploy main + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./specs/book + # keep_files is to prevent PR preview files from being overwritten. + # If we need to overwrite such files, trigger this workflow manually. + keep_files: ${{ github.event_name != 'workflow_dispatch' }} + + - name: Deploy PR preview + # Only run this job if the PR was created from a branch on + # rollkit/rollkit because this job will fail for branches from forks. + if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: ./specs/book diff --git a/.gitignore b/.gitignore index d4362e4b7d6..867ddcf64ff 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ proto/pb proto/tendermint types/pb/tendermint .vscode/launch.json +*/**.html diff --git a/block/block.md b/block/block.md new file mode 100644 index 00000000000..2d45d232166 --- /dev/null +++ b/block/block.md @@ -0,0 +1 @@ +# Block diff --git a/da/da.md b/da/da.md new file mode 100644 index 00000000000..80d0ab82dc4 --- /dev/null +++ b/da/da.md @@ -0,0 +1 @@ +# DA diff --git a/mempool/mempool.md b/mempool/mempool.md new file mode 100644 index 00000000000..63c76e818d1 --- /dev/null +++ b/mempool/mempool.md @@ -0,0 +1 @@ +# Mempool diff --git a/node/node.md b/node/node.md new file mode 100644 index 00000000000..6d9836e17a0 --- /dev/null +++ b/node/node.md @@ -0,0 +1 @@ +# Node diff --git a/p2p/p2p.md b/p2p/p2p.md new file mode 100644 index 00000000000..4dc51b64a0e --- /dev/null +++ b/p2p/p2p.md @@ -0,0 +1 @@ +# P2P diff --git a/specs/.gitignore b/specs/.gitignore new file mode 100644 index 00000000000..7585238efed --- /dev/null +++ b/specs/.gitignore @@ -0,0 +1 @@ +book diff --git a/specs/README.md b/specs/README.md new file mode 100644 index 00000000000..6e350c8cfab --- /dev/null +++ b/specs/README.md @@ -0,0 +1,38 @@ +# Rollkit Specifications + +## Building From Source + +Install [mdbook](https://rust-lang.github.io/mdBook/guide/installation.html) and [mdbook-toc](https://github.com/badboy/mdbook-toc): + +```sh +cargo install mdbook +cargo install mdbook-toc +``` + +To build book: + +```sh +mdbook build +``` + +To serve locally: + +```sh +mdbook serve +``` + +## Contributing + +Specifications are written and stored in the same directory with the implementation code. Since `mdbook` does not support referencing files outside of the book directory, we use a symlink to the `src/specs` directory. This allows us to reference the specifications from the `README.md` and `SUMMARY.md` files in the `src` directory. + +To create a symlink: + +```sh +cd src/specs +ln -s path/to/spec.md +``` + +Markdown files must conform to [GitHub Flavored Markdown](https://github.github.com/gfm/). Markdown must be formatted with: + +- [markdownlint](https://github.com/DavidAnson/markdownlint) +- [Markdown Table Prettifier](https://github.com/darkriszty/MarkdownTablePrettify-VSCodeExt) diff --git a/specs/book.toml b/specs/book.toml new file mode 100644 index 00000000000..37e91e43e1c --- /dev/null +++ b/specs/book.toml @@ -0,0 +1,16 @@ +[book] +authors = ["Rollkit"] +language = "en" +multilingual = false +src = "src" +title = "Rollkit Specifications" + +[output.html] +git-repository-url = "https://github.com/rollkit/rollkit" + +[rust] +edition = "2021" + +[preprocessor.toc] +command = "mdbook-toc" +renderer = ["html"] diff --git a/specs/src/README.md b/specs/src/README.md new file mode 100644 index 00000000000..daf64e3b535 --- /dev/null +++ b/specs/src/README.md @@ -0,0 +1,3 @@ +# Welcome + +Welcome to the Rollkit Specifications. diff --git a/specs/src/SUMMARY.md b/specs/src/SUMMARY.md new file mode 100644 index 00000000000..7faa8d2274b --- /dev/null +++ b/specs/src/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +[Introduction](README.md) + +- [Template](./specs/template.md) +- [Block](./specs/block.md) +- [DA](./specs/da.md) +- [Mempool](./specs/mempool.md) +- [Node](./specs/node.md) +- [P2P](./specs/p2p.md) +- [State](./specs/state.md) +- [Store](./specs/store.md) diff --git a/specs/src/specs/block.md b/specs/src/specs/block.md new file mode 120000 index 00000000000..a5ad0da2ac6 --- /dev/null +++ b/specs/src/specs/block.md @@ -0,0 +1 @@ +../../../block/block.md \ No newline at end of file diff --git a/specs/src/specs/da.md b/specs/src/specs/da.md new file mode 120000 index 00000000000..63d26d4f745 --- /dev/null +++ b/specs/src/specs/da.md @@ -0,0 +1 @@ +../../../da/da.md \ No newline at end of file diff --git a/specs/src/specs/mempool.md b/specs/src/specs/mempool.md new file mode 120000 index 00000000000..08f1cf8113b --- /dev/null +++ b/specs/src/specs/mempool.md @@ -0,0 +1 @@ +../../../mempool/mempool.md \ No newline at end of file diff --git a/specs/src/specs/node.md b/specs/src/specs/node.md new file mode 120000 index 00000000000..8791b9b4b47 --- /dev/null +++ b/specs/src/specs/node.md @@ -0,0 +1 @@ +../../../node/node.md \ No newline at end of file diff --git a/specs/src/specs/p2p.md b/specs/src/specs/p2p.md new file mode 120000 index 00000000000..e3200124a31 --- /dev/null +++ b/specs/src/specs/p2p.md @@ -0,0 +1 @@ +../../../p2p/p2p.md \ No newline at end of file diff --git a/specs/src/specs/state.md b/specs/src/specs/state.md new file mode 120000 index 00000000000..0d5bfd3c62c --- /dev/null +++ b/specs/src/specs/state.md @@ -0,0 +1 @@ +../../../state/state.md \ No newline at end of file diff --git a/specs/src/specs/store.md b/specs/src/specs/store.md new file mode 120000 index 00000000000..ccf6f0ce781 --- /dev/null +++ b/specs/src/specs/store.md @@ -0,0 +1 @@ +../../../store/store.md \ No newline at end of file diff --git a/specs/src/specs/template.md b/specs/src/specs/template.md new file mode 120000 index 00000000000..35b615ac779 --- /dev/null +++ b/specs/src/specs/template.md @@ -0,0 +1 @@ +../../template.md \ No newline at end of file diff --git a/specs/template.md b/specs/template.md new file mode 100644 index 00000000000..d698e5f5a2b --- /dev/null +++ b/specs/template.md @@ -0,0 +1,37 @@ +# Protocol/Component Name + +## Abstract + +Provide a concise description of the purpose of the component for which the +specification is written, along with its contribution to the rollkit or +other relevant parts of the system. Make sure to include proper references to +the relevant sections. + +## Protocol/Component Description + +Offer a comprehensive explanation of the protocol, covering aspects such as data +flow, communication mechanisms, and any other details necessary for +understanding the inner workings of this component. + +## Message Structure/Communication Format + +If this particular component is expected to communicate over the network, +outline the structure of the message protocol, including details such as field +interpretation, message format, and any other relevant information. + +## Assumptions and Considerations + +If there are any assumptions required for the component's correct operation, +performance, security, or other expected features, outline them here. +Additionally, provide any relevant considerations related to security or other +concerns. + +## Implementation + +Include a link to the location where the implementation of this protocol can be +found. Note that specific implementation details should be documented in the +rollkit repository rather than in the specification document. + +## References + +List any references used or cited in the document. diff --git a/state/state.md b/state/state.md new file mode 100644 index 00000000000..da704cc74eb --- /dev/null +++ b/state/state.md @@ -0,0 +1 @@ +# State diff --git a/store/store.md b/store/store.md new file mode 100644 index 00000000000..3f8815b136b --- /dev/null +++ b/store/store.md @@ -0,0 +1 @@ +# Store