Polkadot OmniNode Docs (#6094)

provides low-level documentation on how the omni-node is meant to work.
This is meant to act as reusable material for other teams (e.g.
Papermoon and W3F) to use and integrate into the high level Polkadot
documentation.

Broadly speaking, for omni-node to have great rust-docs, we need to
focus on the following crates, all of which got a bit of love in this
PR:

1. `sp-genesis-builder`
2. `polkadot-omni-node`
3. `polkadot-omni-node-lib`
4. `frame-omni-bencher`

On top of this, we have now: 

* `polkadot_sdk_docs::guides` contains two new steps demonstrating the
most basic version of composing your pallet, putting it into a runtime,
and putting that runtime into omni-node
* `polkadot_sdk_docs::reference_docs::omni_node` to explain in more
detail how omni-node differs from the old-school node.
* `polkadot_sdk_docs::reference_docs::frame_weight_benchmarking` to
finally have a minimal reference about weights and benchmarking.
* It provides tests for some of the steps in
#5568


closes #5568
closes #4781

Next steps

- [x] Ensure the README of the parachain template is up-to-date.
@iulianbarbu
- [ ] Readme for `polkadot-omni-node` and similar is updated. For now,
use `cargo-readme` and copy over the rust-docs.

To build the branch locally and run this:
https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/meta_contributing/index.html#how-to-develop-locally

---------

Co-authored-by: Iulian Barbu <[email protected]>
Co-authored-by: Sebastian Kunert <[email protected]>
Co-authored-by: Michal Kucharczyk <[email protected]>

.gitignore

@@ -41,3 +41,4 @@ runtime/wasm/target/
 substrate.code-workspace
 target/
 *.scale
+justfile

Cargo.toml

@@ -149,6 +149,8 @@ members = [
 	"cumulus/test/service",
 	"cumulus/xcm/xcm-emulator",
 	"docs/sdk",
+	"docs/sdk/packages/guides/first-pallet",
+	"docs/sdk/packages/guides/first-runtime",
 	"docs/sdk/src/reference_docs/chain_spec_runtime",
 	"polkadot",
 	"polkadot/cli",
@@ -806,6 +808,8 @@ hyper = { version = "1.3.1", default-features = false }
 hyper-rustls = { version = "0.24.2" }
 hyper-util = { version = "0.1.5", default-features = false }
 # TODO: remove hyper v0.14 https://github.com/paritytech/polkadot-sdk/issues/4896
+first-pallet = { package = "polkadot-sdk-docs-first-pallet", path = "docs/sdk/packages/guides/first-pallet", default-features = false }
+first-runtime = { package = "polkadot-sdk-docs-first-runtime", path = "docs/sdk/packages/guides/first-runtime", default-features = false }
 hyperv14 = { package = "hyper", version = "0.14.29", default-features = false }
 impl-serde = { version = "0.5.0", default-features = false }
 impl-trait-for-tuples = { version = "0.2.2" }

cumulus/polkadot-omni-node/lib/src/cli.rs

@@ -14,6 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
+//! CLI options of the omni-node. See [`Command`].
+
 use crate::{
 	chain_spec::DiskChainSpecLoader,
 	common::{
@@ -103,6 +105,7 @@ pub enum Subcommand {
 	Benchmark(frame_benchmarking_cli::BenchmarkCmd),
 }
 
+/// CLI Options shipped with `polkadot-omni-node`.
 #[derive(clap::Parser)]
 #[command(
 	propagate_version = true,
@@ -113,9 +116,11 @@ pub struct Cli<Config: CliConfig> {
 	#[arg(skip)]
 	pub(crate) chain_spec_loader: Option<Box<dyn LoadSpec>>,
 
+	/// Possible subcommands. See [`Subcommand`].
 	#[command(subcommand)]
 	pub subcommand: Option<Subcommand>,
 
+	/// The shared parameters with all cumulus-based parachain nodes.
 	#[command(flatten)]
 	pub run: cumulus_client_cli::RunCmd,
 
@@ -200,6 +205,7 @@ impl<Config: CliConfig> SubstrateCli for Cli<Config> {
 	}
 }
 
+/// The relay chain CLI flags. These are passed in after a `--` at the end.
 #[derive(Debug)]
 pub struct RelayChainCli<Config: CliConfig> {
 	/// The actual relay chain cli object.

cumulus/polkadot-omni-node/lib/src/lib.rs

@@ -14,6 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
+//! # Polkadot Omni Node Library
+//!
 //! Helper library that can be used to run a parachain node.
 //!
 //! ## Overview
@@ -37,11 +39,18 @@
 //!
 //! ## Examples
 //!
-//! For an example, see the `polkadot-parachain-bin` crate.
+//! For an example, see the [`polkadot-parachain-bin`](https://crates.io/crates/polkadot-parachain-bin) crate.
+//!
+//! ## Binary
+//!
+//! It can be used to start a parachain node from a provided chain spec file.
+//! It is only compatible with runtimes that use block number `u32` and `Aura` consensus.
+//!
+//! Example: `polkadot-omni-node --chain <chain_spec.json>`
 
 #![deny(missing_docs)]
 
-mod cli;
+pub mod cli;
 mod command;
 mod common;
 mod fake_runtime_api;

cumulus/polkadot-omni-node/lib/src/nodes/manual_seal.rs

@@ -28,7 +28,6 @@ use sc_network::NetworkBackend;
 use sc_service::{build_polkadot_syncing_strategy, Configuration, PartialComponents, TaskManager};
 use sc_telemetry::TelemetryHandle;
 use sp_runtime::traits::Header;
-use sp_timestamp::Timestamp;
 use std::{marker::PhantomData, sync::Arc};
 
 pub struct ManualSealNode<NodeSpec>(PhantomData<NodeSpec>);
@@ -182,7 +181,10 @@ impl<NodeSpec: NodeSpecT> ManualSealNode<NodeSpec> {
 						additional_key_values: None,
 					};
 					Ok((
-						sp_timestamp::InherentDataProvider::new(Timestamp::new(0)),
+						// This is intentional, as the runtime that we expect to run against this
+						// will never receive the aura-related inherents/digests, and providing
+						// real timestamps would cause aura <> timestamp checking to fail.
+						sp_timestamp::InherentDataProvider::new(sp_timestamp::Timestamp::new(0)),
 						mocked_parachain,
 					))
 				}

cumulus/polkadot-omni-node/src/main.rs

@@ -14,12 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Basic polkadot omni-node.
+//! White labeled polkadot omni-node.
 //!
-//! It can be used to start a parachain node from a provided chain spec file.
-//! It is only compatible with runtimes that use block number `u32` and `Aura` consensus.
-//!
-//! Example: `polkadot-omni-node --chain [chain_spec.json]`
+//! For documentation, see [`polkadot_omni_node_lib`].
 
 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]

docs/mermaid/IA.mmd

@@ -8,6 +8,5 @@ flowchart
 
     polkadot_sdk --> substrate
     polkadot_sdk --> frame
-    polkadot_sdk --> polkadot[polkadot node]
     polkadot_sdk --> xcm
 	polkadot_sdk --> templates

docs/sdk/Cargo.toml

@@ -29,6 +29,7 @@ pallet-example-offchain-worker = { workspace = true, default-features = true }
 # How we build docs in rust-docs
 simple-mermaid = "0.1.1"
 docify = { workspace = true }
+serde_json = { workspace = true }
 
 # Polkadot SDK deps, typically all should only be in scope such that we can link to their doc item.
 polkadot-sdk = { features = ["runtime-full"], workspace = true, default-features = true }
@@ -39,6 +40,7 @@ subkey = { workspace = true, default-features = true }
 frame-system = { workspace = true }
 frame-support = { workspace = true }
 frame-executive = { workspace = true }
+frame-benchmarking = { workspace = true }
 pallet-example-authorization-tx-extension = { workspace = true, default-features = true }
 pallet-example-single-block-migrations = { workspace = true, default-features = true }
 frame-metadata-hash-extension = { workspace = true, default-features = true }
@@ -70,6 +72,9 @@ cumulus-primitives-proof-size-hostfunction = { workspace = true, default-feature
 cumulus-client-service = { workspace = true, default-features = true }
 cumulus-primitives-storage-weight-reclaim = { workspace = true, default-features = true }
 
+# Omni Node
+polkadot-omni-node-lib = { workspace = true, default-features = true }
+
 # Pallets and FRAME internals
 pallet-aura = { workspace = true, default-features = true }
 pallet-timestamp = { workspace = true, default-features = true }
@@ -92,6 +97,7 @@ pallet-scheduler = { workspace = true, default-features = true }
 pallet-referenda = { workspace = true, default-features = true }
 pallet-broker = { workspace = true, default-features = true }
 pallet-babe = { workspace = true, default-features = true }
+pallet-grandpa = { workspace = true, default-features = true }
 
 # Primitives
 sp-io = { workspace = true, default-features = true }
@@ -106,6 +112,7 @@ sp-arithmetic = { workspace = true, default-features = true }
 sp-genesis-builder = { workspace = true, default-features = true }
 sp-offchain = { workspace = true, default-features = true }
 sp-version = { workspace = true, default-features = true }
+sp-weights = { workspace = true, default-features = true }
 
 
 # XCM
@@ -117,9 +124,18 @@ xcm-simulator = { workspace = true }
 pallet-xcm = { workspace = true }
 
 # runtime guides
-chain-spec-guide-runtime = { workspace = true }
+
+chain-spec-guide-runtime = { workspace = true, default-features = true }
 
 # Templates
-minimal-template-runtime = { workspace = true }
-solochain-template-runtime = { workspace = true }
-parachain-template-runtime = { workspace = true }
+minimal-template-runtime = { workspace = true, default-features = true }
+solochain-template-runtime = { workspace = true, default-features = true }
+parachain-template-runtime = { workspace = true, default-features = true }
+
+# local packages
+first-runtime = { workspace = true, default-features = true }
+first-pallet = { workspace = true, default-features = true }
+
+[dev-dependencies]
+assert_cmd = "2.0.14"
+rand = "0.8"

docs/sdk/assets/theme.css

@@ -6,6 +6,27 @@
 	--polkadot-purple: #552BBF;
 }
 
+/* Light theme */
+html[data-theme="light"] {
+    --quote-background: #f9f9f9;
+    --quote-border: #ccc;
+    --quote-text: #333;
+}
+
+/* Dark theme */
+html[data-theme="dark"] {
+    --quote-background: #333;
+    --quote-border: #555;
+    --quote-text: #f9f9f9;
+}
+
+/* Ayu theme */
+html[data-theme="ayu"] {
+    --quote-background: #272822;
+    --quote-border: #383830;
+    --quote-text: #f8f8f2;
+}
+
 body.sdk-docs {
 	nav.sidebar>div.sidebar-crate>a>img {
 		width: 190px;
@@ -20,3 +41,17 @@ body.sdk-docs {
 html[data-theme="light"] .sidebar-crate > .logo-container > img {
   content: url("https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/docs/images/Polkadot_Logo_Horizontal_Pink_Black.png");
 }
+
+/* Custom styles for blockquotes */
+blockquote {
+    background-color: var(--quote-background);
+    border-left: 5px solid var(--quote-border);
+    color: var(--quote-text);
+    margin: 1em 0;
+    padding: 1em 1.5em;
+    /* font-style: italic; */
+}
+
+blockquote p {
+    margin: 0;
+}

docs/sdk/packages/guides/first-pallet/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "polkadot-sdk-docs-first-pallet"
+description = "A simple pallet created for the polkadot-sdk-docs guides"
+version = "0.0.0"
+license = "MIT-0"
+authors.workspace = true
+homepage.workspace = true
+repository.workspace = true
+edition.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+codec = { workspace = true }
+scale-info = { workspace = true }
+frame = { workspace = true, features = ["experimental", "runtime"] }
+docify = { workspace = true }
+
+[features]
+default = ["std"]
+std = ["codec/std", "frame/std", "scale-info/std"]