Skip to content

Commit

Permalink
Add documentation around FRAME Origin (#3362)
Browse files Browse the repository at this point in the history
Does the following: 

- Add a reference doc page named `frame_runtime_types`, which explains
what types like `RuntimeOrigin`, `RuntimeCall` etc are.
- On top of it, it adds a reference doc page called `frame_origin` which
explains a few important patterns that we use around origins
- And finally brushes up `#[frame::origin]` docs. 
- Updates the theme, sidebar and favicon to look like: 

<img width="1728" alt="Screenshot 2024-02-20 at 12 16 00"
src="https://github.com/paritytech/polkadot-sdk/assets/5588131/6d60a16b-2081-411b-8869-43b91920cca9">


All of this was inspired by
https://substrate.stackexchange.com/questions/10992/how-do-you-find-the-public-key-for-the-medium-spender-track-origin/10993

closes paritytech/polkadot-sdk-docs#45
closes paritytech/polkadot-sdk-docs#43
contributes / overlaps with
#2638 cc @liamaharon
deprecation companion:
polkadot-developers/substrate-docs#2131
pba-content companion:
Polkadot-Blockchain-Academy/pba-content#977

---------

Co-authored-by: Radha <[email protected]>
Co-authored-by: Sebastian Kunert <[email protected]>
Co-authored-by: Gonçalo Pestana <[email protected]>
Co-authored-by: Liam Aharon <[email protected]>
  • Loading branch information
5 people authored Feb 27, 2024
1 parent f5de090 commit ad01d70
Show file tree
Hide file tree
Showing 21 changed files with 839 additions and 109 deletions.
2 changes: 1 addition & 1 deletion .gitlab/pipeline/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/mermaid/IA.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ flowchart

devhub --> polkadot_sdk
devhub --> reference_docs
devhub --> tutorial
devhub --> guides

polkadot_sdk --> substrate
polkadot_sdk --> frame
Expand Down
3 changes: 3 additions & 0 deletions docs/mermaid/outer_runtime_types.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
flowchart LR
RuntimeCall --"TryInto"--> PalletCall
PalletCall --"Into"--> RuntimeCall
20 changes: 15 additions & 5 deletions docs/sdk/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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" }

Expand Down Expand Up @@ -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" }
Expand All @@ -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"]
139 changes: 139 additions & 0 deletions docs/sdk/headers/header.html
Original file line number Diff line number Diff line change
@@ -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>
16 changes: 16 additions & 0 deletions docs/sdk/headers/theme.css
Original file line number Diff line number Diff line change
@@ -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;
}
54 changes: 0 additions & 54 deletions docs/sdk/headers/toc.html

This file was deleted.

9 changes: 4 additions & 5 deletions docs/sdk/src/guides/your_first_pallet/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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)]
Expand All @@ -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
Expand Down
7 changes: 6 additions & 1 deletion docs/sdk/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//!
Expand All @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions docs/sdk/src/meta_contributing.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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`].
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/sdk/src/reference_docs/extrinsic_encoding.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down
1 change: 0 additions & 1 deletion docs/sdk/src/reference_docs/frame_composite_enums.rs

This file was deleted.

Loading

0 comments on commit ad01d70

Please sign in to comment.