paritytech · juangirini · Oct 31, 2023 · Oct 31, 2023 · Oct 31, 2023 · Oct 31, 2023
diff --git a/.gitignore b/.gitignore
@@ -29,6 +29,7 @@ bin/node-template/Cargo.lock
 nohup.out
 polkadot_argument_parsing
 polkadot.*
+!docs/sdk/src/polkadot_sdk/polkadot.rs
 pwasm-alloc/Cargo.lock
 pwasm-libc/Cargo.lock
 release-artifacts

@@ -125,7 +125,7 @@ build-rustdoc:
         find "$path" -name '*.html' | xargs -I {} -P "$(nproc)" bash -c 'process_file "$@"' _ {}
       }
       inject_simple_analytics "./crate-docs"
-    - echo "<meta http-equiv=refresh content=0;url=polkadot_service/index.html>" > ./crate-docs/index.html
+    - echo "<meta http-equiv=refresh content=0;url=developer_hub/index.html>" > ./crate-docs/index.html
 
 build-implementers-guide:
   stage: build

@@ -313,7 +313,7 @@ node-bench-regression-guard:
   after_script: [""]
 
 # if this fails run `bot update-ui` in the Pull Request or "./scripts/update-ui-tests.sh" locally
-# see ./docs/CONTRIBUTING.md#ui-tests
+# see ./docs/contributor/CONTRIBUTING.md#ui-tests
 test-frame-ui:
   stage: test
   extends:

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -8,6 +8,7 @@ license = "GPL-3.0-only"
 resolver = "2"
 
 members = [
+	"docs/sdk",
 	"bridges/bin/runtime-common",
 	"bridges/modules/grandpa",
 	"bridges/modules/messages",
@@ -186,7 +187,6 @@ members = [
 	"polkadot/xcm/xcm-simulator",
 	"polkadot/xcm/xcm-simulator/example",
 	"polkadot/xcm/xcm-simulator/fuzzer",
-	"substrate",
 	"substrate/bin/minimal/node",
 	"substrate/bin/minimal/runtime",
 	"substrate/bin/node-template/node",
@@ -476,8 +476,7 @@ default-members = [ "polkadot", "substrate/bin/node/cli" ]
 panic = "unwind"
 opt-level = 3
 
-# make sure dev builds with backtrace do
-# not slow us down
+# make sure dev builds with backtrace do not slow us down
 [profile.dev.package.backtrace]
 inherits = "release"
 

diff --git a/README.md b/README.md
@@ -46,12 +46,12 @@ Below are the primary upstream dependencies utilized in this project:
 
 ## Security
 
-The security policy and procedures can be found in [docs/SECURITY.md](./docs/SECURITY.md).
+The security policy and procedures can be found in [docs/contributor/SECURITY.md](./docs/contributor/SECURITY.md).
 
 ## Contributing & Code of Conduct
 
-Ensure you follow our [contribution guidelines](./docs/CONTRIBUTING.md). In every interaction and contribution, this
-project adheres to the [Contributor Covenant Code of Conduct](./docs/CODE_OF_CONDUCT.md).
+Ensure you follow our [contribution guidelines](./docs/contributor/CONTRIBUTING.md). In every interaction and
+contribution, this project adheres to the [Contributor Covenant Code of Conduct](./docs/contributor/CODE_OF_CONDUCT.md).
 
 ## Additional Resources
 

diff --git a/cumulus/README.md b/cumulus/README.md
@@ -4,7 +4,7 @@
 
 This repository contains both the Cumulus SDK and also specific chains implemented on top of this SDK.
 
-If you only want to run a **Polkadot Parachain Node**, check out our [container section](./docs/container.md).
+If you only want to run a **Polkadot Parachain Node**, check out our [container section](./docs/contributor/container.md).
 
 ## Cumulus SDK
 
@@ -34,7 +34,7 @@ A Polkadot [collator](https://wiki.polkadot.network/docs/en/learn-collator) for
 `polkadot-parachain` binary (previously called `polkadot-collator`).
 
 You may run `polkadot-parachain` locally after building it or using one of the container option described
-[here](./docs/container.md).
+[here](./docs/contributor/container.md).
 
 ### Relay Chain Interaction
 To operate a parachain node, a connection to the corresponding relay chain is necessary. This can be achieved in one of
@@ -242,7 +242,7 @@ Once the executable is built, launch collators for each parachain (repeat once e
 ./target/release/polkadot-parachain --chain $CHAIN --validator
 ```
 
-You can also build [using a container](./docs/container.md).
+You can also build [using a container](./docs/contributor/container.md).
 
 ### Parachains
 

diff --git a/cumulus/parachain-template/runtime/src/lib.rs b/cumulus/parachain-template/runtime/src/lib.rs
@@ -513,8 +513,7 @@ impl pallet_parachain_template::Config for Runtime {
 
 // Create the runtime by composing the FRAME pallets that were previously configured.
 construct_runtime!(
-	pub enum Runtime
-	{
+	pub struct Runtime {
 		// System support stuff.
 		System: frame_system = 0,
 		ParachainSystem: cumulus_pallet_parachain_system = 1,

diff --git a/docs/CODE_OF_CONDUCT.md → docs/contributor/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md → docs/contributor/CODE_OF_CONDUCT.md
diff --git a/docs/CONTRIBUTING.md → docs/contributor/CONTRIBUTING.md b/docs/CONTRIBUTING.md → docs/contributor/CONTRIBUTING.md
diff --git a/docs/DEPRECATION_CHECKLIST.md → docs/contributor/DEPRECATION_CHECKLIST.md b/docs/DEPRECATION_CHECKLIST.md → docs/contributor/DEPRECATION_CHECKLIST.md
@@ -45,7 +45,7 @@ We also need [https://docs.substrate.io/](https://docs.substrate.io/) to be upda
 
 ## Announce the deprecation and removal
 
-**At minimum they should be noted in the release log.** Please see how to document a PR [here](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md#documentation).
+**At minimum they should be noted in the release log.** Please see how to document a PR [here](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md#documentation).
 There you can give instructions based on the audience and tell them what they need to do to upgrade the code.
 
 Some breaking changes have a bigger impact than others. When the impact is big the release note is not enough, though

diff --git a/docs/DOCUMENTATION_GUIDELINES.md → docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md → docs/contributor/DOCUMENTATION_GUIDELINES.md
diff --git a/docs/PULL_REQUEST_TEMPLATE.md → docs/contributor/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md → docs/contributor/PULL_REQUEST_TEMPLATE.md
@@ -3,7 +3,7 @@
 ✄ -----------------------------------------------------------------------------
 
 Thank you for your Pull Request! 🙏 Please make sure it follows the contribution guidelines outlined in
-[this document](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md) and fill
+[this document](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) and fill
 out the sections below. Once you're ready to submit your PR for review, please
 delete this section and leave only the text under the "Description" heading.
 
@@ -27,8 +27,8 @@ Closes # (issue number, *if applicable*)
 # Checklist
 
 - [ ] My PR includes a detailed description as outlined in the "Description" section above
-- [ ] My PR follows the [labeling requirements](CONTRIBUTING.md#Process) of this project (at minimum one label for `T`
-  required)
+- [ ] My PR follows the [labeling requirements](docs/contributor/CONTRIBUTING.md#Process) of this project (at minimum
+  one label for `T` required)
 - [ ] I have made corresponding changes to the documentation (if applicable)
 - [ ] I have added tests that prove my fix is effective or that my feature works (if applicable)
 

diff --git a/docs/SECURITY.md → docs/contributor/SECURITY.md b/docs/SECURITY.md → docs/contributor/SECURITY.md
diff --git a/docs/STYLE_GUIDE.md → docs/contributor/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md → docs/contributor/STYLE_GUIDE.md
diff --git a/docs/container.md → docs/contributor/container.md b/docs/container.md → docs/contributor/container.md
diff --git a/docs/docker.md → docs/contributor/docker.md b/docs/docker.md → docs/contributor/docker.md
diff --git a/docs/markdown_linting.md → docs/contributor/markdown_linting.md b/docs/markdown_linting.md → docs/contributor/markdown_linting.md
diff --git a/docs/mermaid/IA.mmd b/docs/mermaid/IA.mmd
@@ -0,0 +1,14 @@
+flowchart
+    parity[paritytech.github.io] --> devhub[developer_hub]
+
+    devhub --> polkadot_sdk
+    devhub --> reference_docs
+    devhub --> tutorial
+
+    polkadot_sdk --> substrate
+    polkadot_sdk --> frame
+    polkadot_sdk --> cumulus
+    polkadot_sdk --> polkadot
+    polkadot_sdk --> xcm
+
+
diff --git a/docs/mermaid/extrinsics.mmd b/docs/mermaid/extrinsics.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    E(Extrinsic) ---> I(Inherent);
+    E --> T(Transaction)
+    T --> ST("Signed (aka. Transaction)")
+    T --> UT(Unsigned)
diff --git a/docs/mermaid/polkadot_sdk_parachain.mmd b/docs/mermaid/polkadot_sdk_parachain.mmd
@@ -0,0 +1,11 @@
+flowchart LR
+	subgraph Parachain[A Polkadot Parachain]
+		ParachainNode[Parachain Node]
+		ParachainRuntime[Parachain Runtime]
+	end
+
+    FRAME -.-> ParachainRuntime
+    Substrate[Substrate Node Libraries] -.-> ParachainNoe
+
+    CumulusC[Cumulus Node Libraries] -.-> ParachainNode
+    CumulusR[Cumulus Runtime Libraries] -.-> ParachainRuntime
diff --git a/docs/mermaid/polkadot_sdk_polkadot.mmd b/docs/mermaid/polkadot_sdk_polkadot.mmd
@@ -0,0 +1,10 @@
+flowchart LR
+
+	subgraph Polkadot[The Polkadot Relay Chain]
+		PolkadotNode[Polkadot Node]
+		PolkadotRuntime[Polkadot Runtime]
+	end
+
+    FRAME -.-> PolkadotRuntime
+    Substrate[Substrate Node Libraries] -.-> PolkadotNode
+
diff --git a/docs/mermaid/polkadot_sdk_substrate.mmd b/docs/mermaid/polkadot_sdk_substrate.mmd
@@ -0,0 +1,8 @@
+flowchart LR
+	subgraph SubstrateChain[A Substrate-based blockchain]
+		Node
+		Runtime
+	end
+
+    FRAME -.-> Runtime
+    Substrate[Substrate Node Libraries] -.-> Node
diff --git a/docs/mermaid/state.mmd b/docs/mermaid/state.mmd
@@ -0,0 +1,16 @@
+flowchart TB
+    subgraph Node[Node's View Of The State 🙈]
+        direction LR
+        0x1234 --> 0x2345
+        0x3456 --> 0x4567
+        0x5678 --> 0x6789
+        :code --> code[wasm code]
+    end
+
+    subgraph Runtime[Runtime's View Of The State 🙉]
+        direction LR
+        ab[alice's balance] --> abv[known value]
+        bb[bob's balance] --> bbv[known value]
+        cb[charlie's balance] --> cbv[known value]
+        c2[:code] --> c22[wasm code]
+    end
diff --git a/docs/mermaid/stf.mmd b/docs/mermaid/stf.mmd
@@ -0,0 +1,21 @@
+flowchart LR
+    %%{init: {'flowchart' : {'curve' : 'linear'}}}%%
+    subgraph BData[Blockchain Database]
+        direction LR
+        BN[Block N] -.-> BN1[Block N+1]
+    end
+
+    subgraph SData[State Database]
+        direction LR
+        SN[State N] -.-> SN1[State N+1] -.-> SN2[State N+2]
+    end
+
+    BN --> STFN[STF]
+    SN --> STFN[STF]
+    STFN[STF] --> SN1
+
+    BN1 --> STFN1[STF]
+    SN1 --> STFN1[STF]
+    STFN1[STF] --> SN2
+
+
diff --git a/docs/mermaid/stf_simple.mmd b/docs/mermaid/stf_simple.mmd
@@ -0,0 +1,4 @@
+flowchart LR
+	B[Block] --> STF
+    S[State] --> STF
+    STF --> NS[New State]
diff --git a/docs/mermaid/substrate_client_runtime.mmd b/docs/mermaid/substrate_client_runtime.mmd
@@ -1,10 +1,12 @@
 graph TB
 subgraph Substrate
 	direction LR
-	subgraph Client
+	subgraph Node
 	end
+
 	subgraph Runtime
 	end
-	Client --runtime-api--> Runtime
-	Runtime --host-functions--> Client
+
+	Node --runtime-api--> Runtime
+	Runtime --host-functions--> Node
 end
diff --git a/docs/mermaid/substrate_dev.mmd b/docs/mermaid/substrate_dev.mmd
@@ -0,0 +1,2 @@
+flowchart LR
+	T[Using a Template] --> P[Writing Your Own FRAME-Based Pallet] --> C[Custom Node]
diff --git a/docs/mermaid/substrate_simple.mmd b/docs/mermaid/substrate_simple.mmd
@@ -1,7 +1,7 @@
 graph TB
 subgraph Substrate
 	direction LR
-	subgraph Client
+	subgraph Node
 	end
 	subgraph Runtime
 	end