most of the stuff done in polkadot_sdk mod

developer-hub/headers/toc.html

@@ -1,31 +1,32 @@
 <script>
 	window.addEventListener("DOMContentLoaded", (event) => {
-	// if the crate is one that starts with `developer_hub`
-	let crate_name = document.querySelector("#main-content > div > h1 > a:nth-child(1)");
-	if (!crate_name.textContent.startsWith("developer_hub")) {
-		console.log("skipping -- not `developer_hub`");
-	}
-
-    let sidebar = document.querySelector(".sidebar");
-    let headers = document.querySelectorAll("#main-content h2, #main-content h3, #main-content h4");
-	console.log(`detected developer_hub: headers: ${headers.length}`);
-
-    let toc = document.createElement("div");
-    toc.classList.add("table-of-contents");
-	toc.appendChild(document.createElement("h2").appendChild(document.createTextNode("Table of Contents")).parentNode);
-
-	// the first two headers are always junk
-    headers.forEach(header => {
-        let link = document.createElement("a");
-        link.href = "#" + header.id;
-        link.textContent = header.textContent;
-        link.className = header.tagName.toLowerCase();
-        toc.appendChild(link);
-    });
-
-    sidebar.insertBefore(toc, sidebar.firstChild);
-	console.log("injecting ToC");
-});
+		// if the crate is one that starts with `developer_hub`
+		let crate_name = document.querySelector("#main-content > div > h1 > a:nth-child(1)");
+		if (!crate_name.textContent.startsWith("developer_hub")) {
+			console.log("skipping -- not `developer_hub`");
+			return;
+		}
+
+		let sidebar = document.querySelector(".sidebar");
+		let headers = document.querySelectorAll("#main-content h2, #main-content h3, #main-content h4");
+		console.log(`detected developer_hub: headers: ${headers.length}`);
+
+		let toc = document.createElement("div");
+		toc.classList.add("table-of-contents");
+		toc.appendChild(document.createElement("h2").appendChild(document.createTextNode("Table of Contents")).parentNode);
+
+		// the first two headers are always junk
+		headers.forEach(header => {
+			let link = document.createElement("a");
+			link.href = "#" + header.id;
+			link.textContent = header.textContent;
+			link.className = header.tagName.toLowerCase();
+			toc.appendChild(link);
+		});
+
+		sidebar.insertBefore(toc, sidebar.firstChild);
+		console.log("injecting ToC");
+	});
 </script>
 <style>
 .table-of-contents {

developer-hub/src/guides/mod.rs

@@ -0,0 +1,25 @@
+//! # Polkadot Developer Hub Guides
+//!
+//! This crate contains a collection of tutorials that are foundational to the developers of
+//! Polkadot SDK. They common user-journeys that are traversed in the Polkadot ecosystem.
+
+/// Write your first simple pallet, learning the most most basic features of FRAME along the way.
+pub mod writing_your_first_pallet;
+
+/// Writing your first real [runtime](`crate::reference_docs::wasm_meta_protocol`), and successfully
+/// compiling it to [WASM](crate::polkadot_sdk::substrate#wasm-build).
+pub mod your_first_runtime;
+
+/// Running the given runtime with a node. No specific consensus mechanism is used at this stage.
+pub mod your_first_node;
+
+/// How to change the consensus engine of both the node and the runtime.
+pub mod changing_consensus;
+
+/// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain and connect
+/// it to a relay-chain.
+pub mod cumulus_enabled_parachain;
+
+/// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between itself
+/// and the relay chain to which it is connected.
+pub mod xcm_enabled_parachain;

developer-hub/src/lib.rs

@@ -12,9 +12,10 @@
 //!
 //! We suggest the following reading sequence:
 //!
-//! - Start by learning about the structure of the [`polkadot_sdk`] and its context.
-//! - Then, head over the [`tutorial`] to get more hand-on practice.
-//! - Whilst reading the tutorial, you might find back-links to [`reference_docs`].
+//! - Start by learning about the the [`polkadot_sdk`], its structure and context.
+//! - Then, head over the [`guides`]. This modules contains in-depth guides about the most important
+//!   user-journeys of the Polkadot SDK.
+//! - Whilst reading the guides, you might find back-links to [crate::`reference_docs`].
 //! - Finally, <https://paritytech.github.io> is the parent website of this crate that contains the
 //!   list of further tools related to the Polkadot SDK.
 //!
@@ -27,6 +28,8 @@
 #![warn(rustdoc::broken_intra_doc_links)]
 #![warn(rustdoc::private_intra_doc_links)]
 
+// TODO: tutorial -> guide
+
 /// Meta information about this crate, how it is built, what principles dictates its evolution and
 /// how one can contribute to it.
 pub mod meta_contributing;
@@ -35,8 +38,11 @@ pub mod meta_contributing;
 /// the tools that are provided as a part of it, and to gain a high level understanding of each.
 pub mod polkadot_sdk;
 /// Reference documents covering in-depth topics across the Polkadot SDK. It is suggested to read
-/// these on-demand, while you are going through the [`tutorial`] or other content.
+/// these on-demand, while you are going through the [`guides`] or other content.
 pub mod reference_docs;
-/// The main polkadot-sdk tutorial, targeted toward those who wish to build parachains FRAME and
-/// Cumulus.
+/// In-depth guides about the most common components of the Polkadot SDK. They are slightly more
+/// high level and broad than reference docs.
+pub mod guides;
+
+// TODO: Deprecated, should remove
 pub mod tutorial;

developer-hub/src/meta_contributing.rs

@@ -100,10 +100,10 @@
 //! ```
 //!
 //! * Before even getting started, what is with all of this `<T: Config>`? We link to
-//! [`reference_docs::trait_based_programming`].
+//! [`crate::reference_docs::trait_based_programming`].
 //! * First, the name. Why is this called `pallet::call`? This goes back to `enum Call`, which is
-//! explained in [`reference_docs::frame_composite_enums`]. Build on top of this!
-//! * Then, what is `origin`? Just an account id? [`reference_docs::frame_origin`].
+//! explained in [`crate::reference_docs::frame_composite_enums`]. Build on top of this!
+//! * Then, what is `origin`? Just an account id? [`crate::reference_docs::frame_origin`].
 //! * Then, what is `DispatchResult`? Why is this called *dispatch*? Probably something that can be
 //! explained in the documentation of [`frame::prelude::DispatchResult`].
 //! * Why is `"SomeStaticString"` a valid error? Because there is implementation for it that you can

developer-hub/src/polkadot_sdk/cumulus.rs

@@ -27,7 +27,7 @@
 //! - [`pallet_timestamp`]
 //! - [`pallet_aura`]
 //! - [`cumulus_pallet_aura_ext`]
-// #![doc = docify::embed!("./src/lib.rs", consensus_pallets)]
+#![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", consensus_pallets)]
 //!
 //!
 //! Finally, a separate macro, similar to
@@ -37,10 +37,6 @@
 //! blocks produced by our parachain.
 #![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", validate_block)]
 //!
-//! ## Example: Running a node
-//!
-//! TODO
-//!
 //! ---
 //!
 //! [FRAME]: crate::polkadot_sdk::frame_runtime

developer-hub/src/polkadot_sdk/frame_runtime.rs

@@ -15,11 +15,12 @@
 //!
 //! ## Introduction
 //!
-//! As described in [`crate::reference_docs::wasm_meta_protocol`], at a high-level substrate-based blockchains are composed of two parts:
+//! As described in [`crate::reference_docs::wasm_meta_protocol`], at a high-level substrate-based
+//! blockchains are composed of two parts:
 //!
 //! 1. A *runtime* which represents the state transition function (i.e. "Business Logic") of a
-//! blockchain, and is encoded as a Wasm blob.
-//! 2. A client whose primary purpose is to execute the given runtime.
+//! blockchain, and is encoded as a WASM blob.
+//! 2. A node whose primary purpose is to execute the given runtime.
 #![doc = simple_mermaid::mermaid!("../../../docs/mermaid/substrate_simple.mmd")]
 //!
 //! *FRAME is the Substrate's framework of choice to build a runtime.*
@@ -29,9 +30,9 @@
 //! ## Pallets
 //!
 //! A pallet is a unit of encapsulated logic. It has a clearly defined responsibility and can be
-//! linked to other pallets. Each pallet should try to only care about its own responsibilities and
-//! make as few assumptions about the general runtime as possible. A pallet is analogous to a
-//! _module_ in the runtime.
+//! linked to other pallets. In order to be reusable, pallets shipped with FRAME strive to only care
+//! about its own responsibilities and make as few assumptions about the general runtime as
+//! possible. A pallet is analogous to a _module_ in the runtime.
 //!
 //! A pallet is defined as a `mod pallet` wrapped by the [`frame::pallet`] macro. Within this macro,
 //! pallet components/parts can be defined. Most notable of these parts are:
@@ -44,6 +45,10 @@
 //! - [Events](frame::pallet_macros::event), allowing a pallet to emit events.
 //! - [Errors](frame::pallet_macros::error), allowing a pallet to emit well-formed errors.
 //!
+//! Some of these pallet components resemble the building blocks of a smart contract. While both
+//! models are programming state transition functions of blockchains, there are crucial differences
+//! between the two. See [`crate::reference_docs::runtime_vs_smart_contract`] for more.
+//!
 //! Most of these components are defined using macros, the full list of which can be found in
 //! [`frame::pallet_macros`].
 //!
@@ -73,7 +78,7 @@
 //!
 //! ## Alternatives 🌈
 //!
-//! There is nothing in the Substrate's client side code-base that mandates the use of FRAME. While
+//! There is nothing in the Substrate's node side code-base that mandates the use of FRAME. While
 //! FRAME makes it very simple to write Substrate-based runtimes, it is by no means intended to be
 //! the only one. At the end of the day, any WASM blob that exposes the right set of runtime APIs is
 //! a valid Runtime form the point of view of a Substrate cliemt (see
@@ -88,53 +93,88 @@
 mod tests {
 	use frame::prelude::*;
 
+	/// A FRAME based pallet. This `mod` is the entry point for everything else. All
+	/// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
+	/// experimental feature to break these parts into different `mod`s. See [`pallet_examples`] for
+	/// more.
 	#[docify::export]
 	#[frame::pallet(dev_mode)]
 	pub mod pallet {
 		use super::*;
 
+		/// The configuration trait of a pallet. Mandatory. Allows a pallet to receive types at a
+		/// later point from the runtime that wishes to contain it. It allows the pallet to be
+		/// parameterized over both types and values.
 		#[pallet::config]
 		pub trait Config: frame_system::Config {
+			/// A type that is not known now, but the runtime that will contain this pallet will
+			/// know it later, therefore we define it here as an associated type.
 			type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent>
 				+ From<Event<Self>>;
+
+			/// A parameterize-able value that we receive later via the `Get<_>` trait.
+			type ValueParameter: Get<u32>;
+
+			/// Similar to [`Config::ValueParameter`], but using `const`. Both are functionally
+			/// equal, but offer different tradeoffs.
+			const ANOTHER_VALUE_PARAMETER: u32;
 		}
 
+		/// A mandatory struct in each pallet. All functions callable by external users (aka.
+		/// transactions) must be attached to this type (see [`frame::pallet_macros::call`]). For
+		/// convenience, internal (private) functions can also be attached to this type.
 		#[pallet::pallet]
 		pub struct Pallet<T>(PhantomData<T>);
 
+		/// The events tha this pallet can emit.
 		#[pallet::event]
 		pub enum Event<T: Config> {}
 
+		/// A storage item that this pallet contains. This will be part of the state root trie/root
+		/// of the blockchain.
 		#[pallet::storage]
 		pub type Value<T> = StorageValue<Value = u32>;
 
+		/// All *dispatchable* call functions (aka. transactions) are attached to `Pallet` in a
+		/// `impl` block.
 		#[pallet::call]
 		impl<T: Config> Pallet<T> {
-			pub fn some_dispatchable(_origin: OriginFor<T>) -> DispatchResult {
+			/// This will be callable by external users, and has two u32s as a parameter.
+			pub fn some_dispatchable(
+				_origin: OriginFor<T>,
+				_param: u32, _other_para: u32
+			) -> DispatchResult {
 				Ok(())
 			}
 		}
 	}
 
+	/// A simple runtime that contains the above pallet and `frame_system`, the mandatory pallet of
+	/// all runtimes. This runtime is for testing, but it shares a lot of similarities with a *real*
+	/// runtime.
 	#[docify::export]
 	pub mod runtime {
 		use super::pallet as pallet_example;
 		use frame::{prelude::*, testing_prelude::*};
 
+		/// The major macro that amalgamates pallets into `struct Runtime`
 		construct_runtime!(
 			pub struct Runtime {
 				System: frame_system,
 				Example: pallet_example,
 			}
 		);
 
+		// These `impl` blocks specify the parameters of each pallet's `trait Config`.
 		#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
 		impl frame_system::Config for Runtime {
 			type Block = MockBlock<Self>;
 		}
 
 		impl pallet_example::Config for Runtime {
 			type RuntimeEvent = RuntimeEvent;
+			type ValueParameter = ConstU32<42>;
+			const ANOTHER_VALUE_PARAMETER: u32 = 42;
 		}
 	}
 }