Add documentation around FRAME Origin

.gitlab/pipeline/build.yml

@@ -91,7 +91,7 @@ build-rustdoc:
     - .run-immediately
   variables:
     SKIP_WASM_BUILD: 1
-    RUSTDOCFLAGS: ""
+    RUSTDOCFLAGS: "--default-theme=ayu --html-in-header ./docs/sdk/headers/header.html --extend-css ./docs/sdk/headers/theme.css"
   artifacts:
     name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}-doc"
     when: on_success

docs/mermaid/IA.mmd

@@ -3,7 +3,7 @@ flowchart
 
     devhub --> polkadot_sdk
     devhub --> reference_docs
-    devhub --> tutorial
+    devhub --> guides
 
     polkadot_sdk --> substrate
     polkadot_sdk --> frame

docs/mermaid/outer_runtime_types.mmd

@@ -0,0 +1,3 @@
+flowchart LR
+    RuntimeCall --"TryInto"--> PalletCall
+    PalletCall --"Into"--> RuntimeCall

docs/sdk/Cargo.toml

@@ -17,7 +17,10 @@ workspace = true
 # Needed for all FRAME-based code
 parity-scale-codec = { version = "3.0.0", default-features = false }
 scale-info = { version = "2.6.0", default-features = false }
-frame = { path = "../../substrate/frame", features = ["experimental", "runtime"] }
+frame = { path = "../../substrate/frame", features = [
+	"experimental",
+	"runtime",
+] }
 pallet-examples = { path = "../../substrate/frame/examples" }
 pallet-default-config-example = { path = "../../substrate/frame/examples/default-config" }
 
@@ -52,7 +55,18 @@ cumulus-pallet-parachain-system = { path = "../../cumulus/pallets/parachain-syst
 ] }
 parachain-info = { package = "staging-parachain-info", path = "../../cumulus/parachains/pallets/parachain-info" }
 pallet-aura = { path = "../../substrate/frame/aura", default-features = false }
+
+# Pallets and FRAME internals
 pallet-timestamp = { path = "../../substrate/frame/timestamp" }
+pallet-balances = { path = "../../substrate/frame/balances" }
+pallet-transaction-payment = { path = "../../substrate/frame/transaction-payment" }
+pallet-utility = { path = "../../substrate/frame/utility" }
+pallet-multisig = { path = "../../substrate/frame/multisig" }
+pallet-proxy = { path = "../../substrate/frame/proxy" }
+pallet-authorship = { path = "../../substrate/frame/authorship" }
+pallet-collective = { path = "../../substrate/frame/collective" }
+pallet-democracy = { path = "../../substrate/frame/democracy" }
+frame-system = { path = "../../substrate/frame/system" }
 
 # Primitives
 sp-io = { path = "../../substrate/primitives/io" }
@@ -64,9 +78,5 @@ sp-runtime = { path = "../../substrate/primitives/runtime" }
 # XCM
 xcm = { package = "staging-xcm", path = "../../polkadot/xcm" }
 
-[dev-dependencies]
-parity-scale-codec = "3.6.5"
-scale-info = "2.9.0"
-
 [features]
 experimental = ["pallet-aura/experimental"]

docs/sdk/headers/header.html

@@ -0,0 +1,139 @@
+<script>
+	function createToC() {
+		let sidebar = document.querySelector(".sidebar");
+		let headers = document.querySelectorAll("#main-content h2, #main-content h3, #main-content h4");
+		console.log(`detected polkadot_sdk_docs: headers: ${headers.length}`);
+
+		let toc = document.createElement("div");
+		toc.classList.add("sidebar-table-of-contents");
+		toc.appendChild(document.createElement("h2").appendChild(document.createTextNode("Table of Contents")).parentNode);
+
+		let modules = document.querySelectorAll("main .item-table a.mod");
+
+		// 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);
+
+			if (header.id == "modules" && header.textContent == "Modules") {
+				modules.forEach(module => {
+					let link = document.createElement("a");
+					link.href = module.href;
+					link.textContent = module.textContent;
+					link.className = "h3";
+
+					toc.appendChild(link);
+				});
+			}
+		});
+
+		// insert toc as the second child in sidebar
+		let sidebar_children = sidebar.children;
+		if (sidebar_children.length > 1) {
+			sidebar.insertBefore(toc, sidebar_children[1]);
+		} else {
+			sidebar.appendChild(toc);
+		}
+	}
+
+	function hideSidebarElements() {
+		// Create the 'Expand for More' button
+		var expandButton = document.createElement('button');
+		expandButton.innerText = 'Expand More Items';
+		expandButton.classList.add('expand-button');
+
+		// Insert the button at the top of the sidebar or before the '.sidebar-elems'
+		var sidebarElems = document.querySelector('.sidebar-elems');
+		sidebarElems.parentNode.insertBefore(expandButton, sidebarElems);
+
+		// Initially hide the '.sidebar-elems'
+		sidebarElems.style.display = 'none';
+
+		// Add click event listener to the button
+		expandButton.addEventListener('click', function() {
+			// Toggle the display of the '.sidebar-elems'
+			if (sidebarElems.style.display === 'none') {
+				sidebarElems.style.display = 'block';
+				expandButton.innerText = 'Collapse';
+			} else {
+				sidebarElems.style.display = 'none';
+				expandButton.innerText = 'Expand for More';
+			}
+		});
+	}
+
+	window.addEventListener("DOMContentLoaded", (event) => {
+		// if the crate is one that starts with `polkadot_sdk_docs`
+		let crate_name = document.querySelector("#main-content > div > h1 > a:nth-child(1)");
+		if (!crate_name.textContent.startsWith("polkadot_sdk_docs")) {
+			console.log("skipping -- not `polkadot_sdk_docs`");
+			return;
+		}
+
+		createToC();
+		hideSidebarElements();
+
+		console.log("updating page based on being `polkadot_sdk_docs` crate");
+	});
+</script>
+
+<style>
+
+nav.side-bar {
+	width: 300px;
+}
+
+.sidebar-table-of-contents {
+    margin-bottom: 1em;
+    padding: 0.5em;
+}
+
+.sidebar-table-of-contents a {
+    display: block;
+    margin: 0.2em 0;
+}
+
+.sidebar-table-of-contents .h2 {
+    font-weight: bold;
+    margin-left: 0;
+}
+
+.sidebar-table-of-contents .h3 {
+    margin-left: 1em;
+}
+
+.sidebar-table-of-contents .h4 {
+    margin-left: 2em;
+}
+
+.sidebar h2.location {
+  display: none;
+}
+
+.sidebar-elems {
+  display: none;
+}
+
+/* Center the 'Expand for More' button */
+.expand-button {
+  display: inline-block; /* Use inline-block for sizing */
+  margin: 10px auto; /* Auto margins for horizontal centering */
+  padding: 5px 10px;
+  background-color: #007bff;
+  color: white;
+  text-align: center;
+  cursor: pointer;
+  border: none;
+  border-radius: 5px;
+  width: auto;
+  /* Centering the button within its parent container */
+  position: relative;
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+</style>

docs/sdk/headers/theme.css

@@ -0,0 +1,16 @@
+:root {
+	--polkadot-pink: #E6007A	;
+	--polkadot-green: #56F39A	;
+	--polkadot-lime: #D3FF33	;
+	--polkadot-cyan: #00B2FF	;
+	--polkadot-purple: #552BBF	;
+  }
+
+body > nav.sidebar > div.sidebar-crate > a > img {
+	/* logo width, given that the sidebar width is 200px; */
+	width: 190px;
+}
+
+body nav.sidebar {
+	flex: 0 0 250px;
+}

docs/sdk/src/guides/your_first_pallet/mod.rs

@@ -128,8 +128,8 @@
 //!
 //! Recall that within our pallet, (almost) all blocks of code are generic over `<T: Config>`. And,
 //! because `trait Config: frame_system::Config`, we can get access to all items in `Config` (or
-//! `frame_system::Config`) using `T::NameOfItem`. This is all within the boundaries of how Rust
-//! traits and generics work. If unfamiliar with this pattern, read
+//! `frame_system::Config`) using `T::NameOfItem`. This is all within the boundaries of how
+//! Rust traits and generics work. If unfamiliar with this pattern, read
 //! [`crate::reference_docs::trait_based_programming`] before going further.
 //!
 //! Crucially, a typical FRAME runtime contains a `struct Runtime`. The main role of this `struct`
@@ -270,7 +270,7 @@
 #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", config_v2)]
 //!
 //! > These `Runtime*` types are better explained in
-//! > [`crate::reference_docs::frame_composite_enums`].
+//! > [`crate::reference_docs::frame_runtime_types`].
 //!
 //! Then, we can rewrite the `transfer` dispatchable as such:
 #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", transfer_v2)]
@@ -285,15 +285,14 @@
 //! [`crate::guides::your_first_pallet::pallet_v2::tests::runtime_v2::RuntimeEvent`].
 //!
 //!
-//!
 //! ## What Next?
 //!
 //! The following topics where used in this guide, but not covered in depth. It is suggested to
 //! study them subsequently:
 //!
 //! - [`crate::reference_docs::safe_defensive_programming`].
 //! - [`crate::reference_docs::frame_origin`].
-//! - [`crate::reference_docs::frame_composite_enums`].
+//! - [`crate::reference_docs::frame_runtime_types`].
 //! - The pallet we wrote in this guide was using `dev_mode`, learn more in
 //!   [`frame::pallet_macros::config`].
 //! - Learn more about the individual pallet items/macros, such as event and errors and call, in

docs/sdk/src/lib.rs

@@ -15,7 +15,7 @@
 //! - 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`].
+//! - Whilst reading the guides, you might find back-links to [`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.
 //!
@@ -25,6 +25,11 @@
 #![doc = simple_mermaid::mermaid!("../../mermaid/IA.mmd")]
 #![warn(rustdoc::broken_intra_doc_links)]
 #![warn(rustdoc::private_intra_doc_links)]
+#![doc(html_favicon_url = "https://polkadot.network/favicon-32x32.png")]
+#![doc(
+	html_logo_url = "https://europe1.discourse-cdn.com/standard21/uploads/polkadot2/original/1X/eb57081e2bb7c39e5fcb1a98b443e423fa4448ae.svg"
+)]
+#![doc(issue_tracker_base_url = "https://github.com/paritytech/polkadot-sdk/issues")]
 
 /// Meta information about this crate, how it is built, what principles dictates its evolution and
 /// how one can contribute to it.

docs/sdk/src/meta_contributing.rs

@@ -101,7 +101,7 @@
 //! * Before even getting started, what is with all of this `<T: Config>`? We link to
 //! [`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 [`crate::reference_docs::frame_composite_enums`]. Build on top of this!
+//! explained in [`crate::reference_docs::frame_runtime_types`]. 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`].
@@ -138,7 +138,9 @@
 //! injected, run:
 //!
 //! ```sh
-//! SKIP_WASM_BUILD=1 RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/toc.html" cargo doc -p polkadot-sdk-docs --no-deps --open
+//! SKIP_WASM_BUILD=1 \
+//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/header.html --extend-css $(pwd)/docs/sdk/headers/theme.css --default-theme=ayu" \
+//! cargo doc -p polkadot-sdk-docs --no-deps --open
 //! ```
 //!
 //! If even faster build time for docs is needed, you can temporarily remove most of the

docs/sdk/src/reference_docs/extrinsic_encoding.rs

@@ -127,7 +127,7 @@
 //! runtimes, a call is represented as an enum of enums, where the outer enum represents the FRAME
 //! pallet being called, and the inner enum represents the call being made within that pallet, and
 //! any arguments to it. Read more about the call enum
-//! [here][crate::reference_docs::frame_composite_enums].
+//! [here][crate::reference_docs::frame_runtime_types].
 //!
 //! FRAME `Call` enums are automatically generated, and end up looking something like this:
 #![doc = docify::embed!("./src/reference_docs/extrinsic_encoding.rs", call_data)]