add doc-only substrate entry point crate

Cargo.toml

@@ -1,3 +1,30 @@
+[package]
+name = "substrate"
+description = "Next-generation framework for blockchain innovation"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+homepage = "https://substrate.io"
+repository = "https://github.com/paritytech/substrate/"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2021"
+version = "0.0.0"
+
+# This list of dependencies is for documentation purposes only.
+[dependencies]
+aquamarine = "0.3.2"
+
+sc-service = { path = "client/service" }
+sc-cli = { path = "client/cli" }
+sc-consensus-aura = { path = "client/consensus/aura" }
+sc-consensus-babe = { path = "client/consensus/babe" }
+sc-consensus-grandpa = { path = "client/consensus/grandpa" }
+sc-consensus-beefy = { path = "client/consensus/beefy" }
+sc-consensus-manual-seal = { path = "client/consensus/manual-seal" }
+sc-consensus-pow = { path = "client/consensus/pow" }
+
+sp-runtime = { path = "primitives/runtime" }
+
+frame-support = { path = "frame/support" }
+
 [workspace]
 resolver = "2"
 

client/cli/src/commands/mod.rs

@@ -15,6 +15,9 @@
 
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+//! Various subcommands that can be included in a substrate-based chain's CLI.
+
 mod build_spec_cmd;
 mod chain_info_cmd;
 mod check_block_cmd;

client/cli/src/lib.rs

@@ -17,6 +17,8 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 //! Substrate CLI library.
+//!
+//! To see a full list of commands available, see [`commands`].
 
 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]
@@ -26,7 +28,7 @@ use clap::{CommandFactory, FromArgMatches, Parser};
 use sc_service::Configuration;
 
 pub mod arg_enums;
-mod commands;
+pub mod commands;
 mod config;
 mod error;
 mod params;

primitives/io/src/lib.rs

@@ -15,19 +15,67 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! I/O host interface for substrate runtime.
+//! # Substrate Primitives: IO
+//!
+//! This crate contains interfaces for the runtime to communicate with the outside world, ergo `io`.
+//! In other context, such interfaces are referred to as "**host functions**".
+//!
+//! Each set of host functions are defined with an instance of the
+//! [`sp_runtime_interface::runtime_interface`] macro.
+//!
+//! Most notably, this crate contains host functions for:
+//!
+//! - [`hashing`]
+//! - [`crypto`]
+//! - [`trie`]
+//! - [`offchain`]
+//! - [`storage`]
+//! - [`allocator`]
+//! - [`logging`]
+//!
+//! All of the default host functions provided by this crate, and by default contained in all
+//! substrate-based clients are amalgamated in [`SubstrateHostFunctions`].
+//!
+//! ## Externalities
+//!
+//! Host functions go hand in hand with the concept of externalities. Externalities are an
+//! environment in which host functions are provided, and thus can be accessed. Some host functions
+//! are only accessible in an externality environment that provides it.
+//!
+//! A typical error for substrate developers is the following:
+//!
+//! ```should_panic
+//! use sp_io::storage::get;
+//! # fn main() {
+//! let data = get(b"hello world");
+//! # }
+//! ```
+//!
+//! This code will panic with the following error:
+//!
+//! ```no_compile
+//! thread 'main' panicked at '`get_version_1` called outside of an Externalities-provided environment.'
+//! ```
+//!
+//! Such error messages should always be interpreted as "code accessing host functions accessed
+//! outside of externalities".
+//!
+//! An externality is any type that implements [`sp_externalities::Externalities`]. A simple example
+//! of which is [`TestExternalities`], which is commonly used in tests and is exported from this
+//! crate.
+//!
+//! ```
+//! use sp_io::{storage::get, TestExternalities};
+//! # fn main() {
+//! TestExternalities::default().execute_with(|| {
+//! 	let data = get(b"hello world");
+//! });
+//! # }
+//! ```
 
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(enable_alloc_error_handler, feature(alloc_error_handler))]
-#![cfg_attr(
-	feature = "std",
-	doc = "Substrate runtime standard library as compiled when linked with Rust's standard library."
-)]
-#![cfg_attr(
-	not(feature = "std"),
-	doc = "Substrate's runtime standard library as compiled without Rust's standard library."
-)]
 
 use sp_std::vec::Vec;
 

scripts/ci/deny.toml

@@ -96,6 +96,7 @@ exceptions = [
     { allow = ["GPL-3.0 WITH Classpath-exception-2.0"], name = "sc-transaction-pool" },
     { allow = ["GPL-3.0 WITH Classpath-exception-2.0"], name = "sc-transaction-pool-api" },
     { allow = ["GPL-3.0 WITH Classpath-exception-2.0"], name = "subkey" },
+    { allow = ["GPL-3.0 WITH Classpath-exception-2.0"], name = "substrate" },
 ]
 
 # Some crates don't have (easily) machine readable licensing information,