Add legacy RPC usage example (#1279)

* Add example using legacy rpc

* Illustrate how account_nonce and system_acc_next eventaully cathces up

* Adapt and add rpc_legacy example to book. Add missing light_client example too

* cargo fmt

---------

Co-authored-by: Fredrik Simonsson <fredrik@nodle.com>

subxt/src/book/mod.rs

@@ -92,6 +92,8 @@
 //!   reading the extrinsics, events and storage at these blocks.
 //! - [Runtime APIs](usage::runtime_apis): Subxt can make calls into pallet runtime APIs to retrieve
 //!   data.
+//! - [Custom values](usage::custom_values): Subxt can access "custom values" stored in the metadata.
+//! - [Raw RPC calls](usage::rpc): Subxt can be used to make raw RPC requests to compatible nodes.
 //!
 //! ## Examples
 //!

subxt/src/book/usage/light_client.rs

@@ -23,7 +23,9 @@
 //! Alternately, you can have the `LightClient` download the chain spec from a trusted node when it
 //! initializes, which is not recommended in production but is useful for examples and testing, as below.
 //!
-//! ## Example
+//! ## Examples
+//!
+//! ### Basic Example
 //!
 //! This example connects to a local chain and submits a transaction. To run this, you first need
 //! to have a local polkadot node running using the following command:
@@ -36,12 +38,19 @@
 //! in the `subxt` crate:
 //!
 //! ```bash
-//! cargo run --example unstable_light_client_tx_basic --features=unstable-light-client
+//! cargo run --example light_client_tx_basic --features=unstable-light-client
 //! ```
 //!
 //! This is the code that will be executed:
 //!
 //! ```rust,ignore
-#![doc = include_str!("../../../examples/unstable_light_client_tx_basic.rs")]
+#![doc = include_str!("../../../examples/light_client_tx_basic.rs")]
 //! ```
 //!
+//! ### Connecting to a parachain
+//!
+//! This example connects to a parachain using the light client. Currently, it's quite verbose to do this.
+//!
+//! ```rust,ignore
+#![doc = include_str!("../../../examples/light_client_parachains.rs")]
+//! ```

subxt/src/book/usage/mod.rs

@@ -12,6 +12,7 @@
 //! - [Runtime APIs](runtime_apis)
 //! - [Unstable Light Client](light_client)
 //! - [Custom Values](custom_values)
+//! - [RPC calls](rpc)
 //!
 //! Alternately, [go back](super).
 
@@ -20,6 +21,7 @@ pub mod constants;
 pub mod custom_values;
 pub mod events;
 pub mod light_client;
+pub mod rpc;
 pub mod runtime_apis;
 pub mod storage;
 pub mod transactions;

subxt/src/book/usage/rpc.rs

@@ -0,0 +1,20 @@
+// Copyright 2019-2023 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+//! # RPC calls
+//!
+//! Subxt exposes low level interfaces that can be used to make RPC requests; [`crate::backend::legacy::rpc_methods`]
+//! and [`crate::backend::unstable::rpc_methods`].
+//!
+//! These interfaces cannot be accessed directly through an [`crate::OnlineClient`]; this is so that the high level
+//! Subxt APIs can target either the "legacy" or the more modern "unstable" sets of RPC methods by selecting an appropriate
+//! [`crate::backend::Backend`]. It also means that there could exist a backend in the future that doesn't use JSON-RPC at all.
+//!
+//! # Example
+//!
+//! Here's an example which calls some legacy JSON-RPC methods, and reuses the same connection to run a full Subxt client
+//!
+//! ```rust,ignore
+#![doc = include_str!("../../../examples/rpc_legacy.rs")]
+//! ```