Skip to content

Commit e1566d0

Browse files
kianenigmaDrW3RKskunertgpestanaliamaharon
authored
Add documentation around FRAME Origin (#3362)
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]>
1 parent 2c38051 commit e1566d0

21 files changed

Lines changed: 839 additions & 109 deletions

File tree

.gitlab/pipeline/build.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ build-rustdoc:
9191
- .run-immediately
9292
variables:
9393
SKIP_WASM_BUILD: 1
94-
RUSTDOCFLAGS: ""
94+
RUSTDOCFLAGS: "--default-theme=ayu --html-in-header ./docs/sdk/headers/header.html --extend-css ./docs/sdk/headers/theme.css"
9595
artifacts:
9696
name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}-doc"
9797
when: on_success

Cargo.lock

Lines changed: 9 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

docs/mermaid/IA.mmd

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ flowchart
33

44
devhub --> polkadot_sdk
55
devhub --> reference_docs
6-
devhub --> tutorial
6+
devhub --> guides
77

88
polkadot_sdk --> substrate
99
polkadot_sdk --> frame
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
flowchart LR
2+
RuntimeCall --"TryInto"--> PalletCall
3+
PalletCall --"Into"--> RuntimeCall

docs/sdk/Cargo.toml

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,10 @@ workspace = true
1717
# Needed for all FRAME-based code
1818
parity-scale-codec = { version = "3.0.0", default-features = false }
1919
scale-info = { version = "2.6.0", default-features = false }
20-
frame = { path = "../../substrate/frame", features = ["experimental", "runtime"] }
20+
frame = { path = "../../substrate/frame", features = [
21+
"experimental",
22+
"runtime",
23+
] }
2124
pallet-examples = { path = "../../substrate/frame/examples" }
2225
pallet-default-config-example = { path = "../../substrate/frame/examples/default-config" }
2326

@@ -52,7 +55,18 @@ cumulus-pallet-parachain-system = { path = "../../cumulus/pallets/parachain-syst
5255
] }
5356
parachain-info = { package = "staging-parachain-info", path = "../../cumulus/parachains/pallets/parachain-info" }
5457
pallet-aura = { path = "../../substrate/frame/aura", default-features = false }
58+
59+
# Pallets and FRAME internals
5560
pallet-timestamp = { path = "../../substrate/frame/timestamp" }
61+
pallet-balances = { path = "../../substrate/frame/balances" }
62+
pallet-transaction-payment = { path = "../../substrate/frame/transaction-payment" }
63+
pallet-utility = { path = "../../substrate/frame/utility" }
64+
pallet-multisig = { path = "../../substrate/frame/multisig" }
65+
pallet-proxy = { path = "../../substrate/frame/proxy" }
66+
pallet-authorship = { path = "../../substrate/frame/authorship" }
67+
pallet-collective = { path = "../../substrate/frame/collective" }
68+
pallet-democracy = { path = "../../substrate/frame/democracy" }
69+
frame-system = { path = "../../substrate/frame/system" }
5670

5771
# Primitives
5872
sp-io = { path = "../../substrate/primitives/io" }
@@ -64,9 +78,5 @@ sp-runtime = { path = "../../substrate/primitives/runtime" }
6478
# XCM
6579
xcm = { package = "staging-xcm", path = "../../polkadot/xcm" }
6680

67-
[dev-dependencies]
68-
parity-scale-codec = "3.6.5"
69-
scale-info = "2.9.0"
70-
7181
[features]
7282
experimental = ["pallet-aura/experimental"]

docs/sdk/headers/header.html

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
<script>
2+
function createToC() {
3+
let sidebar = document.querySelector(".sidebar");
4+
let headers = document.querySelectorAll("#main-content h2, #main-content h3, #main-content h4");
5+
console.log(`detected polkadot_sdk_docs: headers: ${headers.length}`);
6+
7+
let toc = document.createElement("div");
8+
toc.classList.add("sidebar-table-of-contents");
9+
toc.appendChild(document.createElement("h2").appendChild(document.createTextNode("Table of Contents")).parentNode);
10+
11+
let modules = document.querySelectorAll("main .item-table a.mod");
12+
13+
// the first two headers are always junk
14+
headers.forEach(header => {
15+
let link = document.createElement("a");
16+
link.href = "#" + header.id;
17+
link.textContent = header.textContent;
18+
link.className = header.tagName.toLowerCase();
19+
20+
toc.appendChild(link);
21+
22+
if (header.id == "modules" && header.textContent == "Modules") {
23+
modules.forEach(module => {
24+
let link = document.createElement("a");
25+
link.href = module.href;
26+
link.textContent = module.textContent;
27+
link.className = "h3";
28+
29+
toc.appendChild(link);
30+
});
31+
}
32+
});
33+
34+
// insert toc as the second child in sidebar
35+
let sidebar_children = sidebar.children;
36+
if (sidebar_children.length > 1) {
37+
sidebar.insertBefore(toc, sidebar_children[1]);
38+
} else {
39+
sidebar.appendChild(toc);
40+
}
41+
}
42+
43+
function hideSidebarElements() {
44+
// Create the 'Expand for More' button
45+
var expandButton = document.createElement('button');
46+
expandButton.innerText = 'Expand More Items';
47+
expandButton.classList.add('expand-button');
48+
49+
// Insert the button at the top of the sidebar or before the '.sidebar-elems'
50+
var sidebarElems = document.querySelector('.sidebar-elems');
51+
sidebarElems.parentNode.insertBefore(expandButton, sidebarElems);
52+
53+
// Initially hide the '.sidebar-elems'
54+
sidebarElems.style.display = 'none';
55+
56+
// Add click event listener to the button
57+
expandButton.addEventListener('click', function() {
58+
// Toggle the display of the '.sidebar-elems'
59+
if (sidebarElems.style.display === 'none') {
60+
sidebarElems.style.display = 'block';
61+
expandButton.innerText = 'Collapse';
62+
} else {
63+
sidebarElems.style.display = 'none';
64+
expandButton.innerText = 'Expand for More';
65+
}
66+
});
67+
}
68+
69+
window.addEventListener("DOMContentLoaded", (event) => {
70+
// if the crate is one that starts with `polkadot_sdk_docs`
71+
let crate_name = document.querySelector("#main-content > div > h1 > a:nth-child(1)");
72+
if (!crate_name.textContent.startsWith("polkadot_sdk_docs")) {
73+
console.log("skipping -- not `polkadot_sdk_docs`");
74+
return;
75+
}
76+
77+
createToC();
78+
hideSidebarElements();
79+
80+
console.log("updating page based on being `polkadot_sdk_docs` crate");
81+
});
82+
</script>
83+
84+
<style>
85+
86+
nav.side-bar {
87+
width: 300px;
88+
}
89+
90+
.sidebar-table-of-contents {
91+
margin-bottom: 1em;
92+
padding: 0.5em;
93+
}
94+
95+
.sidebar-table-of-contents a {
96+
display: block;
97+
margin: 0.2em 0;
98+
}
99+
100+
.sidebar-table-of-contents .h2 {
101+
font-weight: bold;
102+
margin-left: 0;
103+
}
104+
105+
.sidebar-table-of-contents .h3 {
106+
margin-left: 1em;
107+
}
108+
109+
.sidebar-table-of-contents .h4 {
110+
margin-left: 2em;
111+
}
112+
113+
.sidebar h2.location {
114+
display: none;
115+
}
116+
117+
.sidebar-elems {
118+
display: none;
119+
}
120+
121+
/* Center the 'Expand for More' button */
122+
.expand-button {
123+
display: inline-block; /* Use inline-block for sizing */
124+
margin: 10px auto; /* Auto margins for horizontal centering */
125+
padding: 5px 10px;
126+
background-color: #007bff;
127+
color: white;
128+
text-align: center;
129+
cursor: pointer;
130+
border: none;
131+
border-radius: 5px;
132+
width: auto;
133+
/* Centering the button within its parent container */
134+
position: relative;
135+
left: 50%;
136+
transform: translateX(-50%);
137+
}
138+
139+
</style>

docs/sdk/headers/theme.css

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
:root {
2+
--polkadot-pink: #E6007A ;
3+
--polkadot-green: #56F39A ;
4+
--polkadot-lime: #D3FF33 ;
5+
--polkadot-cyan: #00B2FF ;
6+
--polkadot-purple: #552BBF ;
7+
}
8+
9+
body > nav.sidebar > div.sidebar-crate > a > img {
10+
/* logo width, given that the sidebar width is 200px; */
11+
width: 190px;
12+
}
13+
14+
body nav.sidebar {
15+
flex: 0 0 250px;
16+
}

docs/sdk/headers/toc.html

Lines changed: 0 additions & 54 deletions
This file was deleted.

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

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,8 @@
128128
//!
129129
//! Recall that within our pallet, (almost) all blocks of code are generic over `<T: Config>`. And,
130130
//! because `trait Config: frame_system::Config`, we can get access to all items in `Config` (or
131-
//! `frame_system::Config`) using `T::NameOfItem`. This is all within the boundaries of how Rust
132-
//! traits and generics work. If unfamiliar with this pattern, read
131+
//! `frame_system::Config`) using `T::NameOfItem`. This is all within the boundaries of how
132+
//! Rust traits and generics work. If unfamiliar with this pattern, read
133133
//! [`crate::reference_docs::trait_based_programming`] before going further.
134134
//!
135135
//! Crucially, a typical FRAME runtime contains a `struct Runtime`. The main role of this `struct`
@@ -270,7 +270,7 @@
270270
#![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", config_v2)]
271271
//!
272272
//! > These `Runtime*` types are better explained in
273-
//! > [`crate::reference_docs::frame_composite_enums`].
273+
//! > [`crate::reference_docs::frame_runtime_types`].
274274
//!
275275
//! Then, we can rewrite the `transfer` dispatchable as such:
276276
#![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", transfer_v2)]
@@ -285,15 +285,14 @@
285285
//! [`crate::guides::your_first_pallet::pallet_v2::tests::runtime_v2::RuntimeEvent`].
286286
//!
287287
//!
288-
//!
289288
//! ## What Next?
290289
//!
291290
//! The following topics where used in this guide, but not covered in depth. It is suggested to
292291
//! study them subsequently:
293292
//!
294293
//! - [`crate::reference_docs::safe_defensive_programming`].
295294
//! - [`crate::reference_docs::frame_origin`].
296-
//! - [`crate::reference_docs::frame_composite_enums`].
295+
//! - [`crate::reference_docs::frame_runtime_types`].
297296
//! - The pallet we wrote in this guide was using `dev_mode`, learn more in
298297
//! [`frame::pallet_macros::config`].
299298
//! - Learn more about the individual pallet items/macros, such as event and errors and call, in

docs/sdk/src/lib.rs

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
//! - Start by learning about the the [`polkadot_sdk`], its structure and context.
1616
//! - Then, head over the [`guides`]. This modules contains in-depth guides about the most important
1717
//! user-journeys of the Polkadot SDK.
18-
//! - Whilst reading the guides, you might find back-links to [`crate::reference_docs`].
18+
//! - Whilst reading the guides, you might find back-links to [`reference_docs`].
1919
//! - Finally, <https://paritytech.github.io> is the parent website of this crate that contains the
2020
//! list of further tools related to the Polkadot SDK.
2121
//!
@@ -25,6 +25,11 @@
2525
#![doc = simple_mermaid::mermaid!("../../mermaid/IA.mmd")]
2626
#![warn(rustdoc::broken_intra_doc_links)]
2727
#![warn(rustdoc::private_intra_doc_links)]
28+
#![doc(html_favicon_url = "https://polkadot.network/favicon-32x32.png")]
29+
#![doc(
30+
html_logo_url = "https://europe1.discourse-cdn.com/standard21/uploads/polkadot2/original/1X/eb57081e2bb7c39e5fcb1a98b443e423fa4448ae.svg"
31+
)]
32+
#![doc(issue_tracker_base_url = "https://github.com/paritytech/polkadot-sdk/issues")]
2833

2934
/// Meta information about this crate, how it is built, what principles dictates its evolution and
3035
/// how one can contribute to it.

0 commit comments

Comments
 (0)