further improvement for docify, still buggy, mid level commit

paritytech · Jan 9, 2025 · 5386289 · 5386289
1 parent dd6429e
commit 5386289
Show file tree

Hide file tree

Showing 3 changed files with 242 additions and 34 deletions.
diff --git a/templates/parachain/README.docify.md b/templates/parachain/README.docify.md
@@ -1,69 +1,248 @@
----
-title: Parachain Template
----
+<div align="center">
 
-# Parachain Template
+# Polkadot SDK's Parachain Template
 
-The Parachain Template from the Polkadot SDK is a foundational starting point for developers aiming to build parachains compatible with the Polkadot network. This template is regularly updated following releases in the main Polkadot SDK monorepo.
+<img height="70px" alt="Polkadot SDK Logo" src="https://github.com/paritytech/polkadot-sdk/raw/master/docs/images/Polkadot_Logo_Horizontal_Pink_White.png#gh-dark-mode-only"/>
+<img height="70px" alt="Polkadot SDK Logo" src="https://github.com/paritytech/polkadot-sdk/raw/master/docs/images/Polkadot_Logo_Horizontal_Pink_Black.png#gh-light-mode-only"/>
 
-## Key Features
+> This is a template for creating a [parachain](https://wiki.polkadot.network/docs/learn-parachains) based on Polkadot SDK.
+>
+> This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk).
 
-- **Parachain Development**: The template is designed to facilitate the creation of parachains, leveraging the Cumulus framework to ensure seamless integration with relay chains like Polkadot or Kusama.
-- **Runtime Configuration**: It comes pre-configured with a basic runtime that includes a custom pallet as a starting point, along with essential pallets such as the Balances pallet.
+</div>
+
+## Table of Contents
+
+- [Intro](#intro)
+
+- [Template Structure](#template-structure)
+
+- [Getting Started](#getting-started)
+
+- [Starting a Development Chain](#starting-a-development-chain)
+
+    - [Omni Node](#omni-node-prerequisites)
+    - [Zombienet setup with Omni Node](#zombienet-setup-with-omni-node)
+    - [Parachain Template Node](#parachain-template-node)
+    - [Connect with the Polkadot-JS Apps Front-End](#connect-with-the-polkadot-js-apps-front-end)
+    - [Takeaways](#takeaways)
+
+- [Runtime development](#runtime-development)
+- [Contributing](#contributing)
+- [Getting Help](#getting-help)
+
+## Intro
+
+- ⏫ This template provides a starting point to build a [parachain](https://wiki.polkadot.network/docs/learn-parachains).
+
+- ☁️ It is based on the
+  [Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) framework.
+
+- 🔧 Its runtime is configured with a single custom pallet as a starting point, and a handful of ready-made pallets
+  such as a [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html).
+
+- 👉 Learn more about parachains [here](https://wiki.polkadot.network/docs/learn-parachains)
 
 ## Template Structure
 
-A Polkadot SDK-based project, such as this template, comprises:
+A Polkadot SDK based project such as this one consists of:
 
-- **Node**: The executable binary application that interacts with other nodes in the network, aiming for consensus and acting as an RPC server for blockchain interactions. [Learn more](./node/README.md).
-- **Runtime**: The core logic of the parachain, dictating state transitions and business logic.
-- **Pallets**: Modular components that make up the runtime, each encapsulating specific functionality. [Learn more](./pallets/README.md).
+- 🧮 the [Runtime](./runtime/README.md) - the core logic of the parachain.
+- 🎨 the [Pallets](./pallets/README.md) - from which the runtime is constructed.
+- 💿 a [Node](./node/README.md) - the binary application, not part of the project default-members list and not compiled unless
+  building the project with `--workspace` flag, which builds all workspace members, and is an alternative to
+  [Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html).
 
 ## Getting Started
 
-### Prerequisites
+- 🦀 The template is using the Rust language.
 
-- **Rust Language**: The template is built using Rust. Ensure that Rust is installed on your system by following the [official installation instructions](https://www.rust-lang.org/tools/install).
+- 👉 Check the
+  [Rust installation instructions](https://www.rust-lang.org/tools/install) for your system.
 
-### Building the Node
+- 🛠️ Depending on your operating system and Rust version, there might be additional
+  packages required to compile this template - please take note of the Rust compiler output.
 
-To compile the node without launching it, execute:
+Fetch parachain template code:
 
-```bash
+```sh
+git clone https://github.com/paritytech/polkadot-sdk-parachain-template.git parachain-template
+
+cd parachain-template
+```
+
+## Starting a Development Chain
+
+### Omni Node Prerequisites
+
+[Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html) can
+be used to run the parachain template's runtime. `polkadot-omni-node` binary crate usage is described at a high-level
+[on crates.io](https://crates.io/crates/polkadot-omni-node).
+
+#### Install `polkadot-omni-node`
+
+Please see the installation section at [`crates.io/omni-node`](https://crates.io/crates/polkadot-omni-node).
+
+#### Build `parachain-template-runtime`
+
+```sh
 cargo build --release
 ```
 
-Alternatively, to build the Docker image:
+#### Install `staging-chain-spec-builder`
 
-```bash
-docker build . -t polkadot-sdk-parachain-template
+Please see the installation section at [`crates.io/staging-chain-spec-builder`](https://crates.io/crates/staging-chain-spec-builder).
+
+#### Use `chain-spec-builder` to generate the `chain_spec.json` file
+
+```sh
+chain-spec-builder create --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
+    target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development
 ```
 
-### Local Development Chain
+**Note**: the `relay-chain` and `para-id` flags are mandatory information required by
+Omni Node, and for parachain template case the value for `para-id` must be set to `{{PARACHAIN_ID}}`, since this
+is also the value injected through [ParachainInfo](https://docs.rs/staging-parachain-info/0.17.0/staging_parachain_info/)
+pallet into the `parachain-template-runtime`'s storage. The `relay-chain` value is set in accordance
+with the relay chain ID where this instantiation of parachain-template will connect to.
 
-This project utilizes Zombienet to orchestrate relay chain and parachain nodes. After installing the necessary binaries and ensuring they are in your system's `PATH`, you can start a local development chain with:
+#### Run Omni Node
+
+Start Omni Node with the generated chain spec. We'll start it in development mode (without a relay chain config), producing
+and finalizing blocks based on manual seal, configured below to seal a block with each second.
 
 ```bash
-zombienet --provider native spawn ./zombienet.toml
+polkadot-omni-node --chain <path/to/chain_spec.json> --dev --dev-block-time {{PARACHAIN_ID}}
+```
 
-# Alternatively, using npm:
-npx --yes @zombienet/cli --provider native spawn ./zombienet.toml
+However, such a setup is not close to what would run in production, and for that we need to setup a local
+relay chain network that will help with the block finalization. In this guide we'll setup a local relay chain
+as well. We'll not do it manually, by starting one node at a time, but we'll use [zombienet](https://paritytech.github.io/zombienet/intro.html).
+
+Follow through the next section for more details on how to do it.
+
+### Zombienet setup with Omni Node
+
+Assuming we continue from the last step of the previous section, we have a chain spec and we need to setup a relay chain.
+We can install `zombienet` as described [here](https://paritytech.github.io/zombienet/install.html#installation), and
+`zombienet-omni-node.toml` contains the network specification we want to start.
+
+#### Relay chain prerequisites
+
+Download the `polkadot` (and the accompanying `polkadot-prepare-worker` and `polkadot-execute-worker`) binaries from
+[Polkadot SDK releases](https://github.com/paritytech/polkadot-sdk/releases). Then expose them on `PATH` like so:
+
+```sh
+export PATH="$PATH:<path/to/binaries>"
 ```
 
-Development chains are ephemeral, preconfigured with a genesis state that includes several prefunded development accounts, and utilize development accounts as validators, collators, and `sudo` accounts.
+#### Update `zombienet-omni-node.toml` with a valid chain spec path
 
-### Connecting with Polkadot-JS Apps Front-End
+```toml
+# ...
+[[parachains]]
+id = {{PARACHAIN_ID}}
+chain_spec_path = "<TO BE UPDATED WITH A VALID PATH>"
+# ...
+```
 
-Interact with your local node using the hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps) for both the relay chain and parachain. A hosted version is also available on IPFS. For hosting your own instance, refer to the `polkadot-js/apps` repository.
+#### Start the network
+
+```sh
+zombienet --provider native spawn zombienet-omni-node.toml
+```
+
+### Parachain Template Node
+
+As mentioned in the `Template Structure` section, the `node` crate is optionally compiled and it is an alternative
+to `Omni Node`. Similarly, it requires setting up a relay chain, and we'll use `zombienet` once more.
+
+#### Install the `parachain-template-node`
+
+```sh
+cargo install --path node
+```
+
+#### Setup and start the network
+
+For setup, please consider the instructions for `zombienet` installation [here](https://paritytech.github.io/zombienet/install.html#installation)
+and [relay chain prerequisites](#relay-chain-prerequisites).
+
+We're left just with starting the network:
+
+```sh
+zombienet --provider native spawn zombienet.toml
+```
+
+### Connect with the Polkadot-JS Apps Front-End
+
+- 🌐 You can interact with your local node using the
+  hosted version of the Polkadot/Substrate Portal:
+  [relay chain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944)
+  and [parachain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9988).
+
+- 🪐 A hosted version is also
+  available on [IPFS](https://dotapps.io/).
+
+- 🧑‍🔧 You can also find the source code and instructions for hosting your own instance in the
+  [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository.
+
+### Takeaways
+
+Development parachains:
+
+- 🔗 Connect to relay chains, and we showcased how to connect to a local one.
+- 🧹 Do not persist the state.
+- 💰 Are preconfigured with a genesis state that includes several prefunded development accounts.
+- 🧑‍⚖️ Development accounts are used as validators, collators, and `sudo` accounts.
+
+## Runtime development
+
+We recommend using [`chopsticks`](https://github.com/AcalaNetwork/chopsticks) when the focus is more on the runtime
+development and `OmniNode` is enough as is.
+
+### Install chopsticks
+
+To use `chopsticks`, please install the latest version according to the installation [guide](https://github.com/AcalaNetwork/chopsticks?tab=readme-ov-file#install).
+
+### Build a raw chain spec
+
+Build the `parachain-template-runtime` as mentioned before in this guide and use `chain-spec-builder`
+again but this time by passing `--raw-storage` flag:
+
+```sh
+chain-spec-builder create --raw-storage --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
+    target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development
+```
+
+### Start `chopsticks` with the chain spec
+
+```sh
+npx @acala-network/chopsticks@latest --chain-spec <path/to/chain_spec.json>
+```
+
+### Alternatives
+
+`OmniNode` can be still used for runtime development if using the `--dev` flag, while `parachain-template-node` doesn't
+support it at this moment. It can still be used to test a runtime in a full setup where it is started alongside a
+relay chain network (see [Parachain Template node](#parachain-template-node) setup).
 
 ## Contributing
 
-This template is automatically updated after releases in the main Polkadot SDK monorepo. For contributions, direct pull requests to the source. Please adhere to the monorepo's [contribution guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/CONTRIBUTING.md) and [Code of Conduct](https://github.com/paritytech/polkadot-sdk/blob/master/CODE_OF_CONDUCT.md).
+- 🔄 This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk).
+
+- ➡️ Any pull requests should be directed to this [source](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain).
+
+- 😇 Please refer to the monorepo's
+  [contribution guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) and
+  [Code of Conduct](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CODE_OF_CONDUCT.md).
 
 ## Getting Help
 
-- For general information about Polkadot, the [Polkadot.network](https://polkadot.network/) website is a good starting point.
-- For technical documentation, refer to the [Polkadot SDK documentation resources](https://docs.polkadot.com/).
-- Additionally, you can seek assistance through GitHub issues and the [Substrate StackExchange](https://substrate.stackexchange.com/).
+- 🧑‍🏫 To learn about Polkadot in general, [Polkadot.network](https://polkadot.network/) website is a good starting point.
+
+- 🧑‍🔧 For technical introduction, [here](https://github.com/paritytech/polkadot-sdk#-documentation) are
+  the Polkadot SDK documentation resources.
 
-This template serves as a robust foundation for developing parachains, providing the necessary tools and configurations to streamline the development process.
+- 👥 Additionally, there are [GitHub issues](https://github.com/paritytech/polkadot-sdk/issues) and
+  [Substrate StackExchange](https://substrate.stackexchange.com/).
diff --git a/templates/parachain/runtime/build.rs b/templates/parachain/runtime/build.rs
@@ -1,9 +1,27 @@
+use std::process::Command;
+
 #[cfg(all(feature = "std", feature = "metadata-hash"))]
 #[docify::export(template_enable_metadata_hash)]
 fn main() {
+	println!("cargo:rerun-if-changed=../../parachain/runtime/src/genesis_config_presets.rs");
 	substrate_wasm_builder::WasmBuilder::init_with_defaults()
 		.enable_metadata_hash("UNIT", 12)
 		.build();
+	let docify_command = Command::new("cargo build")
+		.args(&["build"])
+		.current_dir("../../")
+		.output()
+		.expect("Failed to execute docify");
+
+	// Print the output of the docify command for debugging
+	println!("docify output: {:?}", docify_command);
+
+	println!("cargo:rerun-if-changed=../../parachain/runtime/src/genesis_config_presets.rs");
+
+	if !docify_command.status.success() {
+		eprintln!("Failed to run docify: {:?}", docify_command);
+		std::process::exit(1);
+	}
 }
 
 #[cfg(all(feature = "std", not(feature = "metadata-hash")))]

diff --git a/templates/parachain/runtime/src/genesis_config_presets.rs b/templates/parachain/runtime/src/genesis_config_presets.rs
@@ -7,6 +7,16 @@ use alloc::{vec, vec::Vec};
 
 use polkadot_sdk::{staging_xcm as xcm, *};
 
+#[doc::include_str!("../README.md")]
+#[cfg(feature = "generate-readme")]
+
+docify::compile_markdown!(
+    "../../README.docify.md",
+    "../../README.md"
+);
+
+use docify::export;
+
 use cumulus_primitives_core::ParaId;
 use frame_support::build_struct_json_patch;
 use parachains_common::AuraId;
@@ -17,7 +27,8 @@ use sp_keyring::Sr25519Keyring;
 /// The default XCM version to set in genesis config.
 const SAFE_XCM_VERSION: u32 = xcm::prelude::XCM_VERSION;
 /// Parachain id used for genesis config presets of parachain template.
-pub const PARACHAIN_ID: u32 = 1000;
+#[export]
+pub const PARACHAIN_ID: u32 = 2000;
 
 /// Generate the session keys from individual elements.
 ///