Polkadot OmniNode Docs

.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"]