docs: Extends #999. Remove disused package readmes. Rename to sr-metadata. Fix Readme Rustdoc names (#1016)

* docs: Remove safe-mix since is no longer local dependency * docs: Fix existing packages link. Still only includes Substrate Core * docs: Remove empty package Readmes. Remove old docs links. Rename to Readme * docs: Remove link to old docs * misc: Merge latest from master. Renaem to sr-metadata. Fix list of RustDoc package names * Rename substrate-metadata to sr-metadata, since it is in the "srml" subdirectory * Change example to use package name that opens all packages in RustDocs * Fix list of packages names that are available to open in RustDocs * fix typo * fix ordering of CLI options and add missing backslash
2026-06-14 04:01:10 +00:00 · 2018-11-12 21:18:06 +01:00
parent 1f0f3c8f6b
commit 037f9dde10
83 changed files with 320 additions and 855 deletions
@@ -1,13 +1,6 @@

 = Substrate CLI

-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
 Substrate CLI library

 include::doc/shell-completion.adoc[]
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate CLI library.
-// end::description[]

 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]
@@ -1,13 +0,0 @@
-
-= Client
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -1,13 +0,0 @@
-
-= Client DB
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,7 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Client backend that uses RocksDB database as storage.
 //!
 //! # Canonicality vs. Finality
@@ -24,8 +23,6 @@
 //! having discarded heavy state that will allow a chain reorganization.
 //!
 //! Finality implies canonicality but not vice-versa.
-//!
-// end::description[]

 extern crate substrate_client as client;
 extern crate kvdb_rocksdb;
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate Client and associated logic.
-// end::description[]

 #![warn(missing_docs)]
 #![recursion_limit="128"]
@@ -1,12 +0,0 @@
-= Consensus Common
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate Consensus Common.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
-//! Consensus basics and common features
-// end::description[]
+//! Tracks offline validators.

 // This provides "unused" building blocks to other crates
 #![allow(dead_code)]
@@ -1,12 +0,0 @@
-= Consensus Rhododendron (RHD)
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,7 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! BFT Agreement based on a rotating proposer in different rounds.
 //!
 //! Where this crate refers to input stream, should never logically conclude.
@@ -30,7 +29,6 @@
 //! conclude without having witnessed the conclusion.
 //! In general, this future should be pre-empted by the import of a justification
 //! set for this block height.
-// end::description[]

 #![cfg(feature="rhd")]
 // FIXME: doesn't compile - https://github.com/paritytech/substrate/issues/1020
@@ -1,13 +0,0 @@
-
-= Executor
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,7 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Temporary crate for contracts implementations.
 //!
 //! This will be replaced with WASM contracts stored on-chain.
@@ -25,7 +24,6 @@
 //! - init_block(PrevBlock?) -> InProgressBlock
 //! - add_transaction(InProgressBlock) -> InProgressBlock
 //! It is left as is for now as it might be removed before this is ever done.
-// end::description[]

 #![warn(missing_docs)]
 #![recursion_limit="128"]
@@ -1,12 +0,0 @@
-= Finality GRANDPA (aka SHAFT)
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,11 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Integration of the GRANDPA finality gadget into substrate.
 //!
 //! This is a long-running future that produces finality notifications.
-// end::description[]

 extern crate finality_grandpa as grandpa;
 extern crate futures;
@@ -1,13 +0,0 @@
-
-= Keyring
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Support code for the runtime. A set of test accounts.
-// end::description[]

 #[macro_use] extern crate hex_literal;
 #[macro_use] extern crate lazy_static;
@@ -1,13 +0,0 @@
-
-= Keystore
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate. If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Keystore (and session key management) for ed25519 based chains like Polkadot.
-// end::description[]

 extern crate substrate_primitives;
 extern crate parity_crypto as crypto;
@@ -1,13 +0,0 @@
-
-= Network libp2p
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
-//! TODO: Missing doc
-// end::description[]
+//! Substrate libp2p implementation of the ethcore network library

 #![recursion_limit = "128"]

@@ -1,13 +0,0 @@
-
-= Network
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -17,10 +17,8 @@
 #![warn(unused_extern_crates)]
 #![warn(missing_docs)]

-// tag::description[]
 //! Substrate-specific P2P networking: synchronizing blocks, propagating BFT messages.
 //! Allows attachment of an optional subprotocol for chain-specific requests.
-// end::description[]

 extern crate linked_hash_map;
 extern crate parking_lot;
@@ -1,13 +0,0 @@
-
-= Primitives
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Shareable Substrate types.
-// end::description[]

 #![warn(missing_docs)]

@@ -1,14 +0,0 @@
-
-= RPC Server
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
-
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate RPC servers.
-// end::description[]

 #[warn(missing_docs)]

@@ -1,13 +0,0 @@
-
-= RPC
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate RPC interfaces.
-// end::description[]

 #![warn(missing_docs)]

@@ -1,14 +0,0 @@
-
-= Serializer
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
-
@@ -14,12 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate customizable serde serializer.
 //!
 //! The idea is that we can later change the implementation
 //! to something more compact, but for now we're using JSON.
-// end::description[]

 #![warn(missing_docs)]

@@ -1,14 +0,0 @@
-
-= Service
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
-
@@ -14,10 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate service. Starts a thread that spins up the network, client, and extrinsic pool.
 //! Manages communication between them.
-// end::description[]

 #![warn(unused_extern_crates)]

@@ -1,12 +0,0 @@
-= Runtime API
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! API's for interfacing with the runtime via native/wasm.
-// end::description[]

 #![cfg_attr(not(feature = "std"), no_std)]

@@ -1,13 +0,0 @@
-
-= Runtime io
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! This is part of the Substrate runtime.
-// end::description[]

 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(lang_items))]
@@ -1,12 +0,0 @@
-= Runtime Primitives
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,10 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! System manager: Handles all of the top-level stuff; executing block/transaction, setting code
 //! and depositing logs.
-// end::description[]

 #![cfg_attr(not(feature = "std"), no_std)]

@@ -1,13 +0,0 @@
-
-= Runtime Sandbox
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,7 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! This crate provides means to instantiate and execute wasm modules.
 //!
 //! It works even when the user of this library executes from
@@ -30,12 +29,10 @@
 //! When this crate is used in the `std` environment all these functions are implemented by directly
 //! calling the wasm VM.
 //!
-//! Example of possible use-cases for this library are the following:
+//! Examples of possible use-cases for this library are not limited to the following:
 //!
 //! - implementing smart-contract runtimes that use wasm for contract code
 //! - executing a wasm substrate runtime inside of a wasm parachain
-//! - etc
-// end::description[]

 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
@@ -1,14 +0,0 @@
-
-= Runtime std
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
-
@@ -14,10 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Lowest-abstraction level for the Substrate runtime: just exports useful primitives from std
 //! or core/alloc to be used with any code that depends on the runtime.
-// end::description[]

 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(core_intrinsics))]
@@ -1,13 +0,0 @@
-
-= Runtime Version
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Version module for the Substrate runtime; Provides a function that returns the runtime version.
-// end::description[]

 #![cfg_attr(not(feature = "std"), no_std)]

@@ -1,13 +0,0 @@
-
-= State DB
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,7 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! State database maintenance. Handles canonicalization and pruning in the database. The input to
 //! this module is a `ChangeSet` which is basically a list of key-value pairs (trie nodes) that
 //! were added or deleted during block execution.
@@ -29,8 +28,6 @@
 //! # Pruning.
 //! See `RefWindow` for pruning algorithm details. `StateDb` prunes on each canonicalization until pruning
 //! constraints are satisfied.
-//!
-// end::description[]

 #[macro_use] extern crate log;
 #[macro_use] extern crate parity_codec_derive;
@@ -1,13 +0,0 @@
-
-= State Machine
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate state machine implementation.
-// end::description[]

 #![warn(missing_docs)]

@@ -1,13 +0,0 @@
-
-= Telemetry
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,14 +14,12 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Telemetry utils.
 //!
 //! `telemetry` macro may be used anywhere in the Substrate codebase
 //! in order to send real-time logging information to the telemetry
 //! server (if there is one). We use the async drain adapter of `slog`
 //! so that the logging thread doesn't get held up at all.
-// end::description[]

 extern crate parking_lot;
 extern crate ws;
@@ -1,13 +0,0 @@
-
-= Test client
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Client testing utilities.
-// end::description[]

 #![warn(missing_docs)]

@@ -1,13 +0,0 @@
-
-= Test runtime
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! The Substrate runtime. This can be compiled with #[no_std], ready for Wasm.
-// end::description[]

 #![cfg_attr(not(feature = "std"), no_std)]

@@ -526,6 +526,16 @@ dependencies = [
 "sr-std 0.1.0",
 ]

+[[package]]
+name = "srml-metadata"
+version = "0.1.0"
+dependencies = [
+ "parity-codec 2.1.5 (registry+https://github.com/rust-lang/crates.io-index)",
+ "parity-codec-derive 2.1.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "serde 1.0.79 (registry+https://github.com/rust-lang/crates.io-index)",
+ "serde_derive 1.0.79 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "srml-support"
 version = "0.1.0"
@@ -538,7 +548,7 @@ dependencies = [
 "sr-io 0.1.0",
 "sr-primitives 0.1.0",
 "sr-std 0.1.0",
- "substrate-metadata 0.1.0",
+ "srml-metadata 0.1.0",
 ]

 [[package]]
@@ -551,16 +561,6 @@ name = "static_assertions"
 version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"

-[[package]]
-name = "substrate-metadata"
-version = "0.1.0"
-dependencies = [
- "parity-codec 2.1.5 (registry+https://github.com/rust-lang/crates.io-index)",
- "parity-codec-derive 2.1.0 (registry+https://github.com/rust-lang/crates.io-index)",
- "serde 1.0.79 (registry+https://github.com/rust-lang/crates.io-index)",
- "serde_derive 1.0.79 (registry+https://github.com/rust-lang/crates.io-index)",
-]
-
 [[package]]
 name = "substrate-primitives"
 version = "0.1.0"
@@ -1,13 +0,0 @@
-
-= Transaction Pool
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -1,13 +0,0 @@
-
-= transaction-graph
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,7 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Generic Transaction Pool
 //!
 //! The pool is based on dependency graph between transactions
@@ -24,7 +23,6 @@
 //!
 //! TODO [ToDr]
 //! - [ ] Multi-threading (getting ready transactions should not block the pool)
-// end::description[]

 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Substrate transaction pool.
-// end::description[]

 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]
@@ -1,12 +0,0 @@
-= Substrate Trie
-
-.Summary
-[source, toml]
----
-include::Cargo.toml[lines=2..5]
----
-
-.Description
----
-include::src/lib.rs[tag=description]
----
@@ -14,9 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity.  If not, see <http://www.gnu.org/licenses/>.

-// tag::description[]
 //! Utility functions to interact with Substrate's Base-16 Modified Merkle Patricia tree ("trie").
-// end::description[]

 // TODO: no_std