feat(docs): Adds mkdocs for project documentation (#332)

* feat: added docs * wip: pint documentation * Update index.md * Update index.md * docs: update docs * docs: add resources readme * fix: typos * docs: add note about parachain * docs: add standalone chain docs * docs: update run commands * docs: add note * feat(docs): adds docker option in getting-started * feat(docs): adds test chapter in installation * feat(docs): adds summary of e2e testing * feat(docs): note git submodule in e2e tests * feat(docs): fix typo in the submmary of e2e tests Co-authored-by: Redwan <[email protected]> Co-authored-by: Matthias Seitz <[email protected]> Co-authored-by: clearloop <[email protected]>
ChainSafe · Sep 6, 2021 · 37515fd · 37515fd
1 parent 252f339
commit 37515fd
Show file tree

Hide file tree

Showing 19 changed files with 763 additions and 15 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,20 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main 
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: ./mkdocs.yml
+          EXTRA_PACKAGES: build-base
diff --git a/README.md b/README.md
@@ -4,9 +4,11 @@
 
 A Polkadot ecosystem index for investors. A self sustaining auction treasury for parachains.
 
-Organized by the Stateless Money validator, governed by a community that includes Polychain Capital, Hypersphere Ventures, HashKey Capital, Acala, and built by ChainSafe as a StakerDAO product. 
+Organized by the Stateless Money validator, governed by a community that includes Polychain Capital, Hypersphere
+Ventures, HashKey Capital, Acala, and built by ChainSafe as a StakerDAO product.
 
-For more information on the project please visit [Polkadot Index Network Token](https://docs.polkadotindex.com/) documentation.
+For more information on the project please visit [Polkadot Index Network Token](https://docs.polkadotindex.com/)
+documentation.
 
 ❗**Current development should be considered a work in progress.**
 
@@ -21,7 +23,8 @@ Follow these steps to prepare a local Substrate development environment :hammer_
 
 ### Setup
 
-This project currently builds against Rust nightly-2021-01-26. Assuming you have rustup already insatlled set up your local environment:
+This project currently builds against Rust nightly-2021-01-26. Assuming you have rustup already insatlled set up your
+local environment:
 
 ```shell
 rustup install nightly-2021-01-26
@@ -39,15 +42,32 @@ Once the development environment is set up, build the node template. This comman
 cargo build --release
 ```
 
-Note: If the build fails with `(signal: 9, SIGKILL: kill)` it has probably run out of memory. Try freeing some memory or build on another machine.
+Note: If the build fails with `(signal: 9, SIGKILL: kill)` it has probably run out of memory. Try freeing some memory or
+build on another machine.
 
 ## Run
 
+### Development Chain
+
+You can start a standalone development chain with:
+
+```bash
+cargo run -- --dev --instant-sealing
+```
+
+Or if already built
+
+```bash
+./target/release/pint --dev --instant-sealing
+```
+
+This will use the [`node/src/chain_spec/dev.rs`](node/src/chain_spec/dev.rs) chain spec.
+
 ### Local Testnet
 
 Polkadot (release-v0.9.x branch)
 
-```
+```bash
 cargo build --release
 
 ./target/release/polkadot build-spec --chain rococo-local --raw --disable-default-bootnode > rococo_local.json
@@ -59,20 +79,21 @@ cargo build --release
 
 PINT Parachain:
 
-```
+```bash
 # this command assumes the chain spec is in a directory named polkadot that is a sibling of the pint directory
 ./target/release/pint --collator --alice --chain pint-dev --ws-port 9945 --parachain-id 200 --rpc-cors all -- --execution wasm --chain ../polkadot/rococo_local.json --ws-port 9977 --rpc-cors all
 ```
 
 ### Registering on Local Relay Chain
 
-In order to produce blocks you will need to register the parachain as detailed in the [Substrate Cumulus Workshop](https://substrate.dev/cumulus-workshop/#/en/3-parachains/2-register) by going to
+In order to produce blocks you will need to register the parachain as detailed in
+the [Substrate Cumulus Workshop](https://substrate.dev/cumulus-workshop/#/en/3-parachains/2-register) by going to
 
 Developer -> sudo -> paraSudoWrapper -> sudoScheduleParaInitialize(id, genesis)
 
 Ensure you set the `ParaId` to `200` and the `parachain: Bool` to `Yes`.
 
-```
+```bash
 cargo build --release
 # Build the Chain spec
 ./target/release/pint build-spec --disable-default-bootnode > ./pint-local-plain.json
@@ -85,11 +106,18 @@ cargo build --release
 ./target/release/pint export-genesis-wasm > ./para-200.wasm
 ```
 
-
-* [polkadot-launch](https://github.com/paritytech/polkadot-launch) can be run by dropping the proper polkadot binary in the  `./bin` folder and
+* [polkadot-launch](https://github.com/paritytech/polkadot-launch) can be run by dropping the proper polkadot binary in
+  the  `./bin` folder and
     * Run globally
         * `polkadot-launch config.json`
     * Run locally, navigate into polkadot-launch,
         * ``` yarn ```
         * ``` yarn start ```
 
+### Documentation
+
+## Commands
+
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_site
diff --git a/docs/404.html b/docs/404.html
@@ -0,0 +1,25 @@
+---
+layout: default
+permalink: /404.html
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
@@ -0,0 +1,47 @@
+body {
+    color: #BBB !important;
+    font-family: "ubuntu", sans-serif;
+    line-height: 1.75 !important;
+}
+
+header, footer {
+    border: 0 !important;
+    padding: 2% 0 !important;
+}
+
+h1, h2, h3, h4, h5 {
+    color: #CCC;
+    font-weight: 500;
+    padding-top: 2%;
+}
+
+h1.title {
+    font-size: 110%;
+}
+
+b, strong {
+    color: #CCC;
+}
+
+a {
+    color: #e6087b !important;
+}
+
+a:hover {
+    color: #EEE !important;
+    text-decoration: none;
+    transition: 0.1s;
+}
+
+ul, li {
+    padding: 0.5% 0;
+}
+
+code {
+    padding: 4px;
+}
+
+pre {
+    font-size: 17px;
+    padding: 10px 16px;
+}
diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico
diff --git a/docs/assets/img/nav-formula.png b/docs/assets/img/nav-formula.png
diff --git a/docs/assets/img/pint.png b/docs/assets/img/pint.png
diff --git a/docs/assets/pint2.svg b/docs/assets/pint2.svg
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -0,0 +1,157 @@
+---
+layout: default
+title: Installation
+permalink: /getting-started/installation
+---
+
+# Get Started
+
+## Prerequisites
+
+This project currently builds against Rust nightly-2021-01-26. Assuming you have rustup already insatlled set up your local environment:
+
+```shell
+rustup install nightly-2021-01-26
+rustup target add wasm32-unknown-unknown --toolchain nightly-2021-01-26
+rustup override set nightly-2021-01-26
+``` 
+
+## Build
+
+Once the development environment is set up, build the node template. This command will build the
+[Wasm](https://substrate.dev/docs/en/knowledgebase/advanced/executor#wasm-execution) and
+[native](https://substrate.dev/docs/en/knowledgebase/advanced/executor#native-execution) code:
+
+```bash
+cargo build --release
+```
+
+Note: If the build fails with `(signal: 9, SIGKILL: kill)` it has probably run out of memory. Try freeing some memory or build on another machine.
+
+## Run
+
+### Development Chain
+
+You can start a standalone development chain with:
+
+```bash
+cargo run -- --dev --instant-sealing
+```
+
+Or if already built:
+
+```bash
+./target/release/pint --dev --instant-sealing
+```
+
+For [docker](https://github.com/ChainSafe/PINT/blob/main/docker/release.Dockerfile):
+
+```
+docker run chainsafe/pint --dev --instant-sealing
+```
+
+This will use the [`node/src/chain_spec/dev.rs`](../../node/src/chain_spec/dev.rs) chain spec.
+
+### Local Testnet
+
+Polkadot (release-v0.9.x branch)
+
+```
+cargo build --release
+
+./target/release/polkadot build-spec --chain rococo-local --raw --disable-default-bootnode > rococo_local.json
+
+./target/release/polkadot --chain ./rococo_local.json -d cumulus_relay0 --validator --alice --port 9844
+
+./target/release/polkadot --chain ./rococo_local.json -d cumulus_relay1 --validator --bob --port 9955
+```
+
+##### PINT Parachain:
+
+```
+# this command assumes the chain spec is in a directory named polkadot that is a sibling of the pint directory
+./target/release/pint --collator --alice --chain pint-dev --ws-port 9945 --parachain-id 200 --rpc-cors all -- --execution wasm --chain ../polkadot/rococo_local.json --ws-port 9977 --rpc-cors all
+```
+
+### Registering on Local Relay Chain
+
+In order to produce blocks you will need to register the parachain as detailed in the [Substrate Cumulus Workshop](https://substrate.dev/cumulus-workshop/#/en/3-parachains/2-register) by going to
+
+Developer -> sudo -> paraSudoWrapper -> sudoScheduleParaInitialize(id, genesis)
+
+Ensure you set the `ParaId` to `200` and the `parachain: Bool` to `Yes`.
+
+```
+cargo build --release
+# Build the Chain spec
+./target/release/pint build-spec --chain=pint-dev --disable-default-bootnode > ./pint-local-plain.json
+# Build the raw file
+./target/release/pint build-spec --chain=./pint-local-plain.json --raw --disable-default-bootnode > ./pint-local.json
+
+
+# export genesis state and wasm
+./target/release/pint export-genesis-state --chain=pint-dev --parachain-id 200 > para-200-genesis
+./target/release/pint export-genesis-wasm --chain=pint-dev > ./para-200.wasm
+```
+
+
+### Start a Parachain Node (Collator)
+
+From the parachain template working directory:
+
+```bash
+# This assumes a ParaId of 200. Change as needed.
+./target/release/pint \
+-d /tmp/parachain/alice \
+--collator \
+--alice \
+--force-authoring \
+--ws-port 9945 \
+--parachain-id 200 \
+-- \
+--execution wasm \
+--chain pint_local.json
+```
+
+
+
+* [polkadot-launch](https://github.com/paritytech/polkadot-launch) can be run by dropping the proper polkadot binary in the  `./bin` folder and
+    * Run globally
+        * `polkadot-launch config.json`
+    * Run locally, navigate into polkadot-launch,
+        * ``` yarn ```
+        * ``` yarn start ```
+
+
+## Test
+
+### Testing PINT with cargo
+
+```
+cargo test --all-features
+```
+
+Will run the tests of PINT with cargo.
+
+### Testing PINT with polkadot.js
+
+```
+# the e2e tests require `polkadot-launch` as a git submodule
+git submodule update --recursive
+
+# install dependencies and run e2e tests
+cd js && yarn && yarn e2e
+```
+
+Will bootstrap `PINT` with `polkadot-launch` and run all calls of PINT with `polkadot.js`
+to test both `PINT` can connect to `rococo` and PINT calls are workable with `polkadot.js`.
+
+
+## Learn More
+
+- More detailed instructions to use Cumulus parachains are found in the
+  [Cumulus Workshop](https://substrate.dev/cumulus-workshop/#/en/3-parachains/2-register).
+- Refer to the upstream [Substrate Node Template](https://github.com/substrate-developer-hub/substrate-node-template)
+  to learn more about the structure of this project, the capabilities it encapsulates and the way in
+  which those capabilities are implemented.
+- Learn more about how a parachain block is added to a finalized chain [here](https://polkadot.network/the-path-of-a-parachain-block/).