Add subxt documentation (#546)

* Documentation for cli crate

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify calls generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify events generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify constants generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add documentation and simplify storage generation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Add lib documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* macro: Remove `-f bytes` as this is the default

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt/client: Add examples

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* lib_doc: Add documentation to dedicated file

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Link documentation from file

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add more documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add Storage example

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add rpc documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* metadata: Add documentation for errors

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add documentation for the `extrinsic` module

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add documentation for `events` module

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add `Static Metadata Validation` section

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Add `Runtime Updates` section

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Fix link to documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* readme: Remove hardcoded versions

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Move documentation to dedicated folder

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Spaces between examples

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* More details for `types_mod_ident`

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add note for RuntimeGenerator

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Address feedback

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update codegen/src/api/constants.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/lib.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/metadata/metadata_type.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/storage.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Address feedback

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Fix cargo clippy

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update call example

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add example for fetching constants

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Link to examples in subxt.md

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update codegen/src/api/calls.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/calls.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/calls.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/constants.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/constants.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update codegen/src/api/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update docs/subxt.md

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update subxt/src/extrinsic/mod.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update subxt/src/storage.rs

Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

* Update documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update examples/examples/balance_transfer.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/extrinsic/mod.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/rpc.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update subxt/src/updates.rs

Co-authored-by: James Wilson <james@jsdw.me>

* Update docs example with `PolkadotExtrinsicParams`

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Remove extrinsic extra documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* examples: Remove similar transfer example

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Apply cargo fmt

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

Co-authored-by: James Wilson <james@jsdw.me>
Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>

codegen/src/lib.rs

@@ -15,6 +15,38 @@
 // along with subxt.  If not, see <http://www.gnu.org/licenses/>.
 
 //! Library to generate an API for a Substrate runtime from its metadata.
+//!
+//! ## Generated Structure
+//!
+//! The API generator logic:
+//! - At the root there is the `item_mod` provided (ie `pub mod api {}`)
+//! - Pallets are represented by a child module (ie `pub mod PalletName {}`) of the root
+//! - Each pallet exposes as child modules (if applicable):
+//!   - Calls (`pub mod calls {}`)
+//!   - Events (`pub mod events {}`)
+//!   - Storage (`pub mod storage {}`)
+//!   - Constants (`pub mod constants {}`)
+//!
+//! ## Example
+//!
+//! ```rust
+//! use codec::Decode;
+//! use frame_metadata::RuntimeMetadataPrefixed;
+//! use subxt_codegen::DerivesRegistry;
+//!
+//! // Runtime metadata obtained from a node.
+//! let metadata = <RuntimeMetadataPrefixed as Decode>::decode(encoded)?;
+//! // Module under which the API is generated.
+//! let item_mod = syn::parse_quote!(
+//!     pub mod api {}
+//! );
+//! // Default module derivatives.
+//! let mut derives = DerivesRegistry::default();
+//! // Generate the Runtime API.
+//! let generator = subxt_codegen::RuntimeGenerator::new(metadata);
+//! let runtime_api = generator.generate_runtime(item_mod, derives);
+//! println!("{}", runtime_api);
+//! ```
 
 #![deny(unused_crate_dependencies)]