From bb97684112072ea85aa436fc6135d05b76d85231 Mon Sep 17 00:00:00 2001 From: Chevdor Date: Tue, 24 Jul 2018 11:12:53 +0200 Subject: [PATCH] WIP: Asciidoc (#407) * Rename readme * Add some Asciidoc demo * Remove extra lines --- substrate/{README.md => README.adoc} | 93 ++++++------------- substrate/doc/packages.adoc | 33 +++++++ substrate/polkadot/api/README.adoc | 5 + substrate/polkadot/cli/README.adoc | 11 +++ .../polkadot/cli/doc/shell-completion.adoc | 41 ++++++++ substrate/polkadot/collator/README.adoc | 5 + substrate/polkadot/consensus/README.adoc | 5 + substrate/polkadot/executor/README.adoc | 5 + substrate/polkadot/network/README.adoc | 5 + substrate/polkadot/parachain/README.adoc | 5 + substrate/polkadot/primitives/README.adoc | 5 + substrate/polkadot/runtime/README.adoc | 5 + substrate/polkadot/service/README.adoc | 5 + substrate/polkadot/src/README.adoc | 5 + .../polkadot/statement-table/README.adoc | 5 + .../polkadot/transaction-pool/README.adoc | 5 + 16 files changed, 175 insertions(+), 63 deletions(-) rename substrate/{README.md => README.adoc} (67%) create mode 100644 substrate/doc/packages.adoc create mode 100644 substrate/polkadot/api/README.adoc create mode 100644 substrate/polkadot/cli/README.adoc create mode 100644 substrate/polkadot/cli/doc/shell-completion.adoc create mode 100644 substrate/polkadot/collator/README.adoc create mode 100644 substrate/polkadot/consensus/README.adoc create mode 100644 substrate/polkadot/executor/README.adoc create mode 100644 substrate/polkadot/network/README.adoc create mode 100644 substrate/polkadot/parachain/README.adoc create mode 100644 substrate/polkadot/primitives/README.adoc create mode 100644 substrate/polkadot/runtime/README.adoc create mode 100644 substrate/polkadot/service/README.adoc create mode 100644 substrate/polkadot/src/README.adoc create mode 100644 substrate/polkadot/statement-table/README.adoc create mode 100644 substrate/polkadot/transaction-pool/README.adoc diff --git a/substrate/README.md b/substrate/README.adoc similarity index 67% rename from substrate/README.md rename to substrate/README.adoc index 0283479feb..458ddd955b 100644 --- a/substrate/README.md +++ b/substrate/README.adoc @@ -1,139 +1,106 @@ -# Polkadot += Polkadot +:Author: Polkadot developers +:Revision: 0.2.0 +:toc: +:sectnums: Implementation of a https://polkadot.network node in Rust. -## To play +== To play If you'd like to play with Polkadot, you'll need to install a client like this one. First, get Rust (1.26.1 or later) and the support software if you don't already have it: -``` +[source, shell] +---- curl https://sh.rustup.rs -sSf | sh sudo apt install make clang pkg-config libssl-dev -``` +---- Then, install Polkadot PoC-2: -``` +[source, shell] cargo install --git https://github.com/paritytech/polkadot.git --branch v0.2 polkadot -``` You'll now have a `polkadot` binary installed to your `PATH`. You can drop the `--branch v0.2` or run `cargo install --git https://github.com/paritytech/polkadot.git polkadot` to get the very latest version of Polkadot, but these instructions might not work in that case. -### Krumme Lanke Testnet +=== Krumme Lanke Testnet You will connect to the global Krumme Lanke testnet by default. To do this, just use: -``` +[source, shell] polkadot -``` If you want to do anything on it (not that there's much to do), then you'll need to get some Krumme Lanke DOTs. Ask in the Polkadot watercooler. -### Development +=== Development You can run a simple single-node development "network" on your machine by running in a terminal: -``` +[source, shell] polkadot --dev -``` You can muck around by cloning and building the http://github.com/paritytech/polka-ui and http://github.com/paritytech/polkadot-ui or just heading to https://polkadot.js.org/apps. -## Local Two-node Testnet +== Local Two-node Testnet If you want to see the multi-node consensus algorithm in action locally, then you can create a local testnet. You'll need two terminals open. In one, run: -``` +[source, shell] polkadot --chain=local --validator --key Alice -d /tmp/alice -``` and in the other, run: -``` +[source, shell] polkadot --chain=local --validator --key Bob -d /tmp/bob --port 30334 --bootnodes '/ip4/127.0.0.1/tcp/30333/p2p/ALICE_BOOTNODE_ID_HERE' -``` Ensure you replace `ALICE_BOOTNODE_ID_HERE` with the node ID from the output of the first terminal. -## Hacking on Polkadot +== Hacking on Polkadot If you'd actually like hack on Polkadot, you can just grab the source code and build it. Ensure you have Rust and the support software installed: -``` +[source, shell] +---- curl https://sh.rustup.rs -sSf | sh rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly rustup update stable cargo install --git https://github.com/alexcrichton/wasm-gc sudo apt install cmake pkg-config libssl-dev -``` +---- Then, grab the Polkadot source code: -``` +[source, shell] +---- git clone https://github.com/paritytech/polkadot.git cd polkadot -``` +---- Then build the code: -``` +[source, shell] +---- ./build.sh # Builds the WebAssembly binaries cargo build # Builds all native code -``` +---- You can run the tests if you like: -``` +[source, shell] cargo test --all -``` You can start a development chain with: -``` +[source, shell] cargo run -- --dev -``` - -## Shell completion - -The Polkadot cli command supports shell auto-completion. For this to work, you will need to run the completion script matching you build and system. - -Assuming you built a release version using `cargo build --release` and use `bash` run the following: -``` -source target/release/completion-scripts/polkadot.bash -``` - -You can find completion scripts for: -- bash -- fish -- zsh -- elvish -- powershell - -To make this change persistent, you can proceed as follow: -### First install -``` -COMPL_DIR=$HOME/.completion -mkdir -p $COMPL_DIR -cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/ -echo "source $COMPL_DIR/polkadot.bash" >> $HOME/.bash_profile -source $HOME/.bash_profile -``` - -### Update -When you build a new version of Polkadot, the following will ensure you auto-completion script matches the current binary: -``` -COMPL_DIR=$HOME/.completion -mkdir -p $COMPL_DIR -cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/ -source $HOME/.bash_profile -``` +include::doc/packages.adoc[] diff --git a/substrate/doc/packages.adoc b/substrate/doc/packages.adoc new file mode 100644 index 0000000000..f21c307077 --- /dev/null +++ b/substrate/doc/packages.adoc @@ -0,0 +1,33 @@ + +== Cargo Packages + +:leveloffset: +2 + +include::../polkadot/api/README.adoc[] + +include::../polkadot/cli/README.adoc[] + +include::../polkadot/collator/README.adoc[] + +include::../polkadot/consensus/README.adoc[] + +include::../polkadot/executor/README.adoc[] + +include::../polkadot/network/README.adoc[] + +include::../polkadot/parachain/README.adoc[] + +include::../polkadot/primitives/README.adoc[] + +include::../polkadot/runtime/README.adoc[] + +include::../polkadot/service/README.adoc[] + +include::../polkadot/src/README.adoc[] + +include::../polkadot/statement-table/README.adoc[] + +include::../polkadot/transaction-pool/README.adoc[] + +:leveloffset: -2 + diff --git a/substrate/polkadot/api/README.adoc b/substrate/polkadot/api/README.adoc new file mode 100644 index 0000000000..8f382d4f43 --- /dev/null +++ b/substrate/polkadot/api/README.adoc @@ -0,0 +1,5 @@ + += Polkadot API + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/cli/README.adoc b/substrate/polkadot/cli/README.adoc new file mode 100644 index 0000000000..54fa5f3f32 --- /dev/null +++ b/substrate/polkadot/cli/README.adoc @@ -0,0 +1,11 @@ + += Polkadot CLI + +== Summary + +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +include::doc/shell-completion.adoc[] diff --git a/substrate/polkadot/cli/doc/shell-completion.adoc b/substrate/polkadot/cli/doc/shell-completion.adoc new file mode 100644 index 0000000000..2486bed09e --- /dev/null +++ b/substrate/polkadot/cli/doc/shell-completion.adoc @@ -0,0 +1,41 @@ + +== Shell completion + +The Polkadot cli command supports shell auto-completion. For this to work, you will need to run the completion script matching you build and system. + +Assuming you built a release version using `cargo build --release` and use `bash` run the following: + +[source, shell] +source target/release/completion-scripts/polkadot.bash + +You can find completion scripts for: +- bash +- fish +- zsh +- elvish +- powershell + +To make this change persistent, you can proceed as follow: + +.First install + +[source, shell] +---- +COMPL_DIR=$HOME/.completion +mkdir -p $COMPL_DIR +cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/ +echo "source $COMPL_DIR/polkadot.bash" >> $HOME/.bash_profile +source $HOME/.bash_profile +---- + +.Update + +When you build a new version of Polkadot, the following will ensure you auto-completion script matches the current binary: + +[source, shell] +---- +COMPL_DIR=$HOME/.completion +mkdir -p $COMPL_DIR +cp -f target/release/completion-scripts/polkadot.bash $COMPL_DIR/ +source $HOME/.bash_profile +---- diff --git a/substrate/polkadot/collator/README.adoc b/substrate/polkadot/collator/README.adoc new file mode 100644 index 0000000000..3a5408b489 --- /dev/null +++ b/substrate/polkadot/collator/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Collator + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/consensus/README.adoc b/substrate/polkadot/consensus/README.adoc new file mode 100644 index 0000000000..a3ac5f631c --- /dev/null +++ b/substrate/polkadot/consensus/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Consensus + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/executor/README.adoc b/substrate/polkadot/executor/README.adoc new file mode 100644 index 0000000000..1c91cccab5 --- /dev/null +++ b/substrate/polkadot/executor/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Executor + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/network/README.adoc b/substrate/polkadot/network/README.adoc new file mode 100644 index 0000000000..1c2ad29b1b --- /dev/null +++ b/substrate/polkadot/network/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Network + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/parachain/README.adoc b/substrate/polkadot/parachain/README.adoc new file mode 100644 index 0000000000..fbce59a188 --- /dev/null +++ b/substrate/polkadot/parachain/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Parachain + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/primitives/README.adoc b/substrate/polkadot/primitives/README.adoc new file mode 100644 index 0000000000..a8468a0cd9 --- /dev/null +++ b/substrate/polkadot/primitives/README.adoc @@ -0,0 +1,5 @@ + += Polkadot primitives + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/runtime/README.adoc b/substrate/polkadot/runtime/README.adoc new file mode 100644 index 0000000000..86dc313134 --- /dev/null +++ b/substrate/polkadot/runtime/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Runtime + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/service/README.adoc b/substrate/polkadot/service/README.adoc new file mode 100644 index 0000000000..3de3867128 --- /dev/null +++ b/substrate/polkadot/service/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Service + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/src/README.adoc b/substrate/polkadot/src/README.adoc new file mode 100644 index 0000000000..fed228df0b --- /dev/null +++ b/substrate/polkadot/src/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Src + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/statement-table/README.adoc b/substrate/polkadot/statement-table/README.adoc new file mode 100644 index 0000000000..402f55108f --- /dev/null +++ b/substrate/polkadot/statement-table/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Statement table + +placeholder +//TODO Write content :) diff --git a/substrate/polkadot/transaction-pool/README.adoc b/substrate/polkadot/transaction-pool/README.adoc new file mode 100644 index 0000000000..868a3434b3 --- /dev/null +++ b/substrate/polkadot/transaction-pool/README.adoc @@ -0,0 +1,5 @@ + += Polkadot Transactin pool + +placeholder +//TODO Write content :)