Remove polkadot doc from substrate (#700)

* Improve doc

- convert some md to adoc
- include contrib docs to the main readme
- add readme for some packages and include them

* Bring changes from 46c9333fff into the replacing adoc file

* Minor fixes

* Remove files irrelevant for substrate

* Remove old polkadot related doc

substrate/substrate/bft/README.adoc

@@ -0,0 +1,13 @@
+
+= Substrate BFT
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/bft/src/lib.rs

@@ -14,6 +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[]
 //! BFT Agreement based on a rotating proposer in different rounds.
 //!
 //! Where this crate refers to input stream, should never logically conclude.
@@ -29,6 +30,7 @@
 //! 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[]
 
 #![recursion_limit="128"]
 

substrate/substrate/cli/README.adoc

@@ -1,11 +1,13 @@
 
 = Substrate CLI
 
-== Summary
-
+.Summary
 [source, toml]
 ----
 include::Cargo.toml[lines=2..5]
 ----
 
+.Description
+Polkadot CLI library
+
 include::doc/shell-completion.adoc[]

substrate/substrate/cli/src/lib.rs

@@ -14,7 +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[]
 //! Substrate CLI library.
+// end::description[]
 
 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]

substrate/substrate/client/README.adoc

@@ -0,0 +1,13 @@
+
+= Client
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/client/db/src/lib.rs

@@ -14,7 +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[]
 //! Client backend that uses RocksDB database as storage.
+// end::description[]
 
 extern crate substrate_client as client;
 extern crate kvdb_rocksdb;

substrate/substrate/codec/README.adoc

@@ -0,0 +1,13 @@
+
+= Codec
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/codec/src/lib.rs

@@ -14,7 +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[]
 //! Implements a serialization and deserialization codec for simple marshalling.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(alloc))]

substrate/substrate/ed25519/README.adoc

@@ -0,0 +1,13 @@
+
+= ED25519
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/ed25519/src/lib.rs

@@ -14,7 +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[]
 //! Simple Ed25519 API.
+// end::description[]
 
 extern crate ring;
 extern crate base58;

substrate/substrate/environmental/README.adoc

@@ -0,0 +1,13 @@
+
+= Environmental
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/environmental/src/lib.rs

@@ -14,6 +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[]
 //! Safe global references to stack variables.
 //!
 //! Set up a global reference with environmental! macro giving it a name and type.
@@ -39,6 +40,7 @@
 //!   stuff();	// safe! doesn't do anything.
 //! }
 //! ```
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(const_fn))]

substrate/substrate/executor/README.adoc

@@ -0,0 +1,13 @@
+
+= Executor
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/executor/src/lib.rs

@@ -14,6 +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[]
 //! Temporary crate for contracts implementations.
 //!
 //! This will be replaced with WASM contracts stored on-chain.
@@ -24,6 +25,7 @@
 //! - init_block(PrevBlock?) -> InProgressBlock
 //! - add_transaction(InProgressBlock) -> InProgressBlock
 //! I leave it as is for now as it might be removed before this is ever done.
+// end::description[]
 
 #![warn(missing_docs)]
 #![recursion_limit="128"]

substrate/substrate/extrinsic-pool/README.adoc

@@ -0,0 +1,13 @@
+
+= extrinsic-pool
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/extrinsic-pool/src/lib.rs

@@ -14,11 +14,13 @@
 // 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 extrinsic pool.
+// end::description[]
+
 #![warn(missing_docs)]
 #![warn(unused_extern_crates)]
 
-//! Generic extrinsic pool.
-
 extern crate futures;
 extern crate parking_lot;
 extern crate substrate_runtime_primitives as runtime_primitives;

substrate/substrate/keyring/README.adoc

@@ -0,0 +1,13 @@
+
+= Keyring
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/keyring/src/lib.rs

@@ -14,7 +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[]
 //! Support code for the runtime.
+// end::description[]
 
 #[macro_use] extern crate hex_literal;
 #[macro_use] extern crate lazy_static;

substrate/substrate/keystore/README.adoc

@@ -0,0 +1,13 @@
+
+= Keystore
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/keystore/src/lib.rs

@@ -14,7 +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[]
 //! Keystore (and session key management) for ed25519 based chains like Polkadot.
+// end::description[]
 
 extern crate parity_crypto as crypto;
 extern crate subtle;

substrate/substrate/misbehavior-check/README.adoc

@@ -0,0 +1,13 @@
+
+= Misbehavior-check
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/misbehavior-check/src/lib.rs

@@ -14,7 +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[]
 //! Utility for substrate-based runtimes that want to check misbehavior reports.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 

substrate/substrate/network-libp2p/README.adoc

@@ -0,0 +1,13 @@
+
+= Network libp2p
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/network-libp2p/src/lib.rs

@@ -14,6 +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[]
+//! TODO: Missing doc
+// end::description[]
+
 #![recursion_limit="128"]
 #![type_length_limit = "268435456"]
 

substrate/substrate/network/README.adoc

@@ -0,0 +1,13 @@
+
+= Network
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/network/src/lib.rs

@@ -17,8 +17,10 @@
 #![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 ethcore_io as core_io;
 extern crate linked_hash_map;

substrate/substrate/primitives/README.adoc

@@ -0,0 +1,13 @@
+
+= Primitives
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/primitives/src/lib.rs

@@ -14,7 +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[]
 //! Shareable Polkadot types.
+// end::description[]
 
 #![warn(missing_docs)]
 

substrate/substrate/pwasm-alloc/README.adoc

@@ -0,0 +1,25 @@
+
+= Pwasm-alloc
+
+Parity WASM contracts standard library libc bindings.
+
+See https://paritytech.github.io/pwasm-std/pwasm_alloc/ for the documentation.
+
+== License
+
+`pwasm_alloc` is primarily distributed under the terms of both the MIT
+license and the Apache License (Version 2.0), at your choice.
+
+See LICENSE-APACHE, and LICENSE-MIT for details.
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
+

substrate/substrate/pwasm-alloc/README.md

@@ -1,12 +0,0 @@
-# pwasm-libc
-
-Parity WASM contracts standard library libc bindings
-
-[Documentation](https://paritytech.github.io/pwasm-std/pwasm_alloc/)
-
-# License
-
-`pwasm_alloc` is primarily distributed under the terms of both the MIT
-license and the Apache License (Version 2.0), at your choice.
-
-See LICENSE-APACHE, and LICENSE-MIT for details.

substrate/substrate/pwasm-alloc/src/lib.rs

@@ -3,7 +3,9 @@
 #![no_std]
 #![crate_type = "rlib"]
 
+// tag::description[]
 //! Custom allocator crate for wasm
+// end::description[]
 
 /// Wasm allocator
 pub struct WasmAllocator;

substrate/substrate/pwasm-libc/README.adoc

@@ -1,12 +1,24 @@
-# pwasm-libc
+
+= Pwasm-libc
 
 Parity WASM contracts standard library libc bindings
 
-[Documentation](https://paritytech.github.io/pwasm-std/pwasm_libc/)
+https://paritytech.github.io/pwasm-std/pwasm_libc/[Documentation]
 
-# License
+== License
 
 `pwasm-libc` is primarily distributed under the terms of both the MIT
 license and the Apache License (Version 2.0), at your choice.
 
 See LICENSE-APACHE, and LICENSE-MIT for details.
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/pwasm-libc/src/lib.rs

@@ -2,7 +2,9 @@
 #![cfg_attr(feature = "strict", deny(warnings))]
 #![no_std]
 
+// tag::description[]
 //! libc externs crate
+// end::description[]
 
 extern "C" {
 	fn ext_memcpy(dest: *mut u8, src: *const u8, n: usize) -> *mut u8;

substrate/substrate/rpc-servers/README.adoc

@@ -0,0 +1,14 @@
+
+= RPC Server
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
+

substrate/substrate/rpc-servers/src/lib.rs

@@ -14,7 +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[]
 //! Substrate RPC servers.
+// end::description[]
 
 #[warn(missing_docs)]
 

substrate/substrate/rpc/README.adoc

@@ -0,0 +1,13 @@
+
+= RPC
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/rpc/src/lib.rs

@@ -14,7 +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[]
 //! Substrate RPC interfaces.
+// end::description[]
 
 #![warn(missing_docs)]
 

substrate/substrate/runtime-io/README.adoc

@@ -0,0 +1,13 @@
+
+= Runtime io
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/runtime-io/src/lib.rs

@@ -14,7 +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[]
 //! This is part of the Substrate runtime.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(lang_items))]

substrate/substrate/runtime-sandbox/README.adoc

@@ -0,0 +1,13 @@
+
+= Runtime Sandbox
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/runtime-sandbox/src/lib.rs

@@ -14,6 +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 crate provides means of instantiation and execution of wasm modules.
 //!
 //! It works even when the user of this library is itself executes
@@ -34,6 +35,7 @@
 //! - implementing smart-contract runtimes which uses wasm for contract code
 //! - executing wasm substrate runtime inside of a wasm parachain
 //! - etc
+// end::description[]
 
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]

substrate/substrate/runtime-std/README.adoc

@@ -0,0 +1,14 @@
+
+= Runtime std
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
+

substrate/substrate/runtime-std/src/lib.rs

@@ -14,8 +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[]
 //! 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(panic_handler))]

substrate/substrate/runtime-support/README.adoc

@@ -0,0 +1,14 @@
+
+= Runtime Support
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
+

substrate/substrate/runtime-support/src/lib.rs

@@ -14,7 +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[]
 //! Support code for the runtime.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(alloc))]

substrate/substrate/runtime/README.adoc

@@ -0,0 +1,6 @@
+
+= Runtime
+
+Set of libs for the substrate runtime.
+
+TODO: Add READMEs to packages.

substrate/substrate/runtime/primitives/src/generic/mod.rs

@@ -14,7 +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[]
 //! Generic implementations of Extrinsic/Header/Block.
+// end::description[]
 
 mod unchecked_extrinsic;
 mod checked_extrinsic;

substrate/substrate/serializer/README.adoc

@@ -0,0 +1,14 @@
+
+= Serializer
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
+

substrate/substrate/serializer/src/lib.rs

@@ -14,10 +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[]
 //! 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)]
 

substrate/substrate/service/README.adoc

@@ -0,0 +1,14 @@
+
+= Service
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
+

substrate/substrate/service/src/lib.rs

@@ -14,8 +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 service. Starts a thread that spins the network, the client and the extrinsic pool.
 //! Manages communication between them.
+// end::description[]
 
 #![warn(unused_extern_crates)]
 

substrate/substrate/state-db/README.adoc

@@ -0,0 +1,13 @@
+
+= State DB
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/state-db/src/lib.rs

@@ -14,6 +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[]
 //! State database maintenance. Handles finalization 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,6 +30,7 @@
 //! See `RefWindow` for pruning algorithm details. `StateDb` prunes on each finalization until pruning
 //! constraints are satisfied.
 //!
+// end::description[]
 
 #[macro_use] extern crate log;
 #[macro_use] extern crate substrate_codec_derive;

substrate/substrate/state-machine/README.adoc

@@ -0,0 +1,13 @@
+
+= State Machine
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/state-machine/src/lib.rs

@@ -14,7 +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[]
 //! Substrate state machine implementation.
+// end::description[]
 
 #![warn(missing_docs)]
 

substrate/substrate/telemetry/README.adoc

@@ -0,0 +1,13 @@
+
+= Telemetry
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/telemetry/src/lib.rs

@@ -14,12 +14,14 @@
 // 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 be used from whereever 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 websocket as ws;

substrate/substrate/test-client/README.adoc

@@ -0,0 +1,13 @@
+
+= Test client
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/test-client/src/lib.rs

@@ -14,7 +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[]
 //! Client testing utilities.
+// end::description[]
 
 #![warn(missing_docs)]
 

substrate/substrate/test-runtime/README.adoc

@@ -0,0 +1,13 @@
+
+= Test runtime
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----

substrate/substrate/test-runtime/src/lib.rs

@@ -14,7 +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[]
 //! The Substrate runtime. This can be compiled with #[no_std], ready for Wasm.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]