Fix documentation examples (#568)

* Fix documentation examples

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

* CI: Add `cargo test --doc`

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

* Update .github/workflows/rust.yml

Co-authored-by: Niklas Adolfsson <niklasadolfsson1@gmail.com>

* Remove docs/subxt.md and move documentation to subxt/lib.rs

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

* Hide polkadot interface for `events/mod.rs`

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

* docs: Use `#` for headers

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

Co-authored-by: Niklas Adolfsson <niklasadolfsson1@gmail.com>

.github/workflows/rust.yml

@@ -99,6 +99,12 @@ jobs:
       - name: Check internal documentation links
         run: RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc -vv --workspace --no-deps --document-private-items
 
+      - name: Run cargo test on documentation
+        uses: actions-rs/cargo@v1.0.3
+        with:
+            command: test
+            args: --doc
+
   tests:
     name: Cargo test
     runs-on: ubuntu-latest

README.md

@@ -24,7 +24,7 @@ a different node then the `metadata` command accepts a `--url` argument.
 
 ## Subxt Documentation
 
-For more details regarding utilizing subxt, please visit the [documentation](docs/subxt.md).
+For more details regarding utilizing subxt, please visit the [documentation](https://docs.rs/subxt/latest/subxt/).
 
 ## Integration Testing
 

codegen/src/lib.rs

@@ -29,13 +29,16 @@
 //!
 //! ## Example
 //!
-//! ```rust
+//! ```no_run
+//! use std::fs;
 //! use codec::Decode;
 //! use frame_metadata::RuntimeMetadataPrefixed;
 //! use subxt_codegen::DerivesRegistry;
 //!
+//! let encoded = fs::read("../artifacts/polkadot_metadata.scale").unwrap();
+//!
 //! // Runtime metadata obtained from a node.
-//! let metadata = <RuntimeMetadataPrefixed as Decode>::decode(encoded)?;
+//! let metadata = <RuntimeMetadataPrefixed as Decode>::decode(&mut &*encoded).unwrap();
 //! // Module under which the API is generated.
 //! let item_mod = syn::parse_quote!(
 //!     pub mod api {}

subxt/src/client.rs

@@ -97,17 +97,23 @@ impl ClientBuilder {
         self
     }
 
-    /// Creates a new Client.
+    /// Builder for [Client].
     ///
-    /// # Example
+    /// # Examples
     ///
-    /// ```rust
+    /// ```no_run
     /// use subxt::{ClientBuilder, DefaultConfig};
     ///
-    /// let client = ClientBuilder::new()
-    ///     .set_url("wss://rpc.polkadot.io:443")
-    ///     .build::<DefaultConfig>()
-    ///     .await?;
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     // Build the client.
+    ///     let client = ClientBuilder::new()
+    ///          .set_url("wss://rpc.polkadot.io:443")
+    ///          .build::<DefaultConfig>()
+    ///          .await
+    ///          .unwrap();
+    ///     // Use the client...
+    /// }
     /// ```
     pub async fn build<T: Config>(self) -> Result<Client<T>, BasicError> {
         let client = if let Some(client) = self.client {
@@ -208,14 +214,26 @@ impl<T: Config> Client<T> {
     /// performing runtime updates, while the API is still in use.
     /// Without performing runtime updates the submitted extrinsics may fail.
     ///
-    /// # Example
+    /// # Examples
     ///
-    /// ```rust
+    /// ```no_run
+    /// # use subxt::{ClientBuilder, DefaultConfig};
+    /// #
+    /// # #[tokio::main]
+    /// # async fn main() {
+    /// #    let client = ClientBuilder::new()
+    /// #         .set_url("wss://rpc.polkadot.io:443")
+    /// #         .build::<DefaultConfig>()
+    /// #         .await
+    /// #         .unwrap();
+    /// #
     /// let update_client = client.updates();
+    /// // Spawn a new background task to handle runtime updates.
     /// tokio::spawn(async move {
     ///     let result = update_client.perform_runtime_updates().await;
     ///     println!("Runtime update finished with result={:?}", result);
     /// });
+    /// # }
     /// ```
     pub fn updates(&self) -> UpdateClient<T> {
         UpdateClient::new(

subxt/src/events/mod.rs

@@ -21,7 +21,7 @@
 //!
 //! This module is wrapped by the generated API in `RuntimeAPI::EventsApi`.
 //!
-//! # Example
+//! # Examples
 //!
 //! ## Subscribe to all events
 //!
@@ -31,12 +31,23 @@
 //!
 //! To obtain the events from a given block use `at()`.
 //!
-//! ```rust
-//! let mut events = api.events().subscribe().await?;
+//! ```no_run
+//! # use futures::StreamExt;
+//! # use subxt::{ClientBuilder, DefaultConfig, PolkadotExtrinsicParams};
+//! # #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
+//! # pub mod polkadot {}
+//! # #[tokio::main]
+//! # async fn main() {
+//! # let api = ClientBuilder::new()
+//! #     .build()
+//! #     .await
+//! #     .unwrap()
+//! #     .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, PolkadotExtrinsicParams<DefaultConfig>>>();
+//! let mut events = api.events().subscribe().await.unwrap();
 //!
 //! while let Some(ev) = events.next().await {
 //!     // Obtain all events from this block.
-//!     let ev: subxt::Events<_, _> = ev?;
+//!     let ev: subxt::Events<_, _> = ev.unwrap();
 //!     // Print block hash.
 //!     println!("Event at block hash {:?}", ev.block_hash());
 //!     // Iterate over all events.
@@ -45,6 +56,7 @@
 //!         println!("Event details {:?}", event_details);
 //!     }
 //! }
+//! # }
 //! ```
 //!
 //! ## Filter events
@@ -55,16 +67,32 @@
 //! returned directly. Otherwise, we'll be given a corresponding tuple of `Option`'s, with exactly
 //! one variant populated each time.
 //!
-//! ```rust
-//! let mut events = api
+//! ```no_run
+//! # use futures::StreamExt;
+//! # use subxt::{ClientBuilder, DefaultConfig, PolkadotExtrinsicParams};
+//!
+//! #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
+//! pub mod polkadot {}
+//!
+//! # #[tokio::main]
+//! # async fn main() {
+//! # let api = ClientBuilder::new()
+//! #     .build()
+//! #     .await
+//! #     .unwrap()
+//! #     .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, PolkadotExtrinsicParams<DefaultConfig>>>();
+//!
+//! let mut transfer_events = api
 //!     .events()
 //!     .subscribe()
-//!     .await?
+//!     .await
+//!     .unwrap()
 //!     .filter_events::<(polkadot::balances::events::Transfer,)>();
 //!
 //! while let Some(transfer_event) = transfer_events.next().await {
 //!     println!("Balance transfer event: {transfer_event:?}");
 //! }
+//! # }
 //! ```
 
 mod decoding;