minor updates to the substrate doc crate (#14614)

Author: kianenigma

bin/utils/chain-spec-builder/src/lib.rs

@@ -20,7 +20,14 @@
 //!
 //! A chain-spec is short for `chain-configuration`. See the [`sc-chain-spec`] for more information.
 //!
+//! Note that this binary is analogous to the `build-spec` subcommand, contained in typical
+//! substrate-based nodes. This particular binary is capable of building a more sophisticated chain
+//! specification that can be used with the substrate-node, ie. [`node-cli`].
+//!
 //! See [`ChainSpecBuilder`] for a list of available commands.
+//!
+//! [`sc-chain-spec`]: ../sc_chain_spec/index.html
+//! [`node-cli`]: ../node_cli/index.html
 
 use std::path::{Path, PathBuf};
 

client/chain-spec/src/lib.rs

@@ -116,15 +116,19 @@
 //! ```json
 //! // The human readable name of the chain.
 //! "name": "Flaming Fir",
+//!
 //! // The id of the chain.
 //! "id": "flamingfir9",
+//!
 //! // The chain type of this chain.
 //! // Possible values are `Live`, `Development`, `Local`.
 //! "chainType": "Live",
+//!
 //! // A list of multi addresses that belong to boot nodes of the chain.
 //! "bootNodes": [
 //!   "/dns/0.flamingfir.paritytech.net/tcp/30333/p2p/12D3KooWLK2gMLhWsYJzjW3q35zAs9FDDVqfqVfVuskiGZGRSMvR",
 //! ],
+//!
 //! // Optional list of "multi address, verbosity" of telemetry endpoints.
 //! // The verbosity goes from `0` to `9`. With `0` being the mode with the lowest verbosity.
 //! "telemetryEndpoints": [
@@ -133,19 +137,24 @@
 //!     0
 //!   ]
 //! ],
+//!
 //! // Optional networking protocol id that identifies the chain.
 //! "protocolId": "fir9",
+//!
 //! // Optional fork id. Should most likely be left empty.
 //! // Can be used to signal a fork on the network level when two chains have the
 //! // same genesis hash.
 //! "forkId": "random_fork",
+//!
 //! // Custom properties.
 //! "properties": {
 //!   "tokenDecimals": 15,
 //!   "tokenSymbol": "FIR"
 //! },
+//!
 //! // Deprecated field. Should be ignored.
 //! "consensusEngine": null,
+//!
 //! // The genesis declaration of the chain.
 //! //
 //! // `runtime`, `raw`, `stateRootHash` denote the type of the genesis declaration.
@@ -159,6 +168,7 @@
 //! //   type depends on the hash used by the chain.
 //! //
 //! "genesis": { "runtime": {} },
+//!
 //! /// Optional map of `block_number` to `wasm_code`.
 //! ///
 //! /// The given `wasm_code` will be used to substitute the on-chain wasm code starting with the
@@ -172,6 +182,8 @@
 //! "codeSubstitutes": [],
 //! ```
 //!
+//! See [`ChainSpec`] for a trait representation of the above.
+//!
 //! The chain spec can be extended with other fields that are opaque to the default chain spec.
 //! Specific node implementations will need to be able to deserialize these extensions.
 

scripts/ci/gitlab/pipeline/build.yml

@@ -153,7 +153,7 @@ build-rustdoc:
     - .test-refs
   variables:
     SKIP_WASM_BUILD: 1
-    DOC_INDEX_PAGE: "sc_service/index.html" # default redirected page
+    DOC_INDEX_PAGE: "substrate/index.html" # default redirected page
     # this variable gets overriden by "rusty-cachier environment inject", use the value as default
     CARGO_TARGET_DIR: "$CI_PROJECT_DIR/target"
   artifacts:

src/lib.rs

@@ -105,19 +105,51 @@
 //! * `pallet-*` and `frame-*` crates, located under `./frame` folder. These are the crates related
 //!   to FRAME. See [`frame_support`] for more information.
 //!
+//! ### Wasm Build
+//!
+//! Many of the Substrate crates, such as entire `sp-*`, need to compile to both Wasm (when a Wasm
+//! runtime is being generated) and native (for example, when testing). To achieve this, Substrate
+//! follows the convention of the Rust community, and uses a `feature = "std"` to signify that a
+//!  crate is being built with the standard library, and is built for native. Otherwise, it is built
+//!  for `no_std`.
+//!
+//! This can be summarized in `#![cfg_attr(not(feature = "std"), no_std)]`, which you can often find
+//! in any Substrate-based runtime.
+//!
+//! Substrate-based runtimes use [`substrate-wasm-builder`] in their `build.rs` to automatically
+//! build their Wasm files as a part of normal build commandsOnce built, the wasm file is placed in
+//! `./target/{debug|release}/wbuild/{runtime_name}.wasm`.
+//!
 //! ### Binaries
 //!
 //! Multiple binaries are shipped with substrate, the most important of which are located in the
 //! `./bin` folder.
 //!
 //! * [`node`] is an extensive substrate node that contains the superset of all runtime and client
 //!   side features. The corresponding runtime, called [`kitchensink_runtime`] contains all of the
-//!   modules that are provided with `FRAME`. This node and runtime is only used for testing.
+//!   modules that are provided with `FRAME`. This node and runtime is only used for testing and
+//!   demonstration.
+//!     * [`chain-spec-builder`]: Utility to build more detailed chain-specs for the aforementioned
+//!       node. Other projects typically contain a `build-spec` subcommand that does the same.
 //! * [`node-template`]: a template node that contains a minimal set of features and can act as a
 //!   starting point of a project.
 //! * [`subkey`]: Substrate's key management utility.
-//! * [`chain-spec-builder`]: Substrate's utility to build *chain specifications*. Such
-//!   specifications can then be used with `--chain` argument of a typical substrate node's CLI.
+//!
+//! ### Anatomy of a Binary Crate
+//!
+//! From the above, [`node`] and [`node-template`] are essentially blueprints of a substrate-based
+//! project, as the name of the latter is implying. Each substrate-based project typically contains
+//! the following:
+//!
+//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file.
+//!   This file typically contains the [`frame_support::construct_runtime`] macro, which is the
+//!   final definition of a runtime.
+//!
+//! * Under `./node`, a `main.rs`, which is the point, and a `./service.rs`, which contains all the
+//!   client side components. Skimming this file yields an overview of the networking, database,
+//!   consensus and similar client side components.
+//!
+//! > The above two are conventions, not rules.
 //!
 //! ## Parachain?
 //!
@@ -132,7 +164,7 @@
 //!
 //! Additional noteworthy crates within substrate:
 //!
-//! - RPC APIs of a Substrate node: [`sc-rpc-api`]
+//! - RPC APIs of a Substrate node: [`sc-rpc-api`]/[`sc-rpc`]
 //! - CLI Options of a Substrate node: [`sc-cli`]
 //! - All of the consensus related crates provided by Substrate:
 //!     - [`sc-consensus-aura`]
@@ -151,6 +183,7 @@
 //!
 //! Notable upstream crates:
 //!
+//! - [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec)
 //! - [`parity-db`](https://github.com/paritytech/parity-db)
 //! - [`trie`](https://github.com/paritytech/trie)
 //! - [`parity-common`](https://github.com/paritytech/parity-common)
@@ -172,6 +205,7 @@
 //! [`sc-client-db`]: ../sc_client_db/index.html
 //! [`sc-network`]: ../sc_network/index.html
 //! [`sc-rpc-api`]: ../sc_rpc_api/index.html
+//! [`sc-rpc`]: ../sc_rpc/index.html
 //! [`sc-cli`]: ../sc_cli/index.html
 //! [`sc-consensus-aura`]: ../sc_consensus_aura/index.html
 //! [`sc-consensus-babe`]: ../sc_consensus_babe/index.html
@@ -182,8 +216,9 @@
 //! [`node`]: ../node_cli/index.html
 //! [`node-template`]: ../node_template/index.html
 //! [`kitchensink_runtime`]: ../kitchensink_runtime/index.html
-//! [`subkey`]: ..//subkey/index.html
-//! [`chian-spec-builder`]: ../chain_spec_builder/index.html
+//! [`subkey`]: ../subkey/index.html
+//! [`chain-spec-builder`]: ../chain_spec_builder/index.html
+//! [`substrate-wasm-builder`]: https://crates.io/crates/substrate-wasm-builder
 
 #![deny(rustdoc::broken_intra_doc_links)]
 #![deny(rustdoc::private_intra_doc_links)]