generate docs for feature gated items

codegen/Cargo.toml

@@ -40,3 +40,10 @@ bitvec = { workspace = true }
 scale-info = { workspace = true, features = ["bit-vec"] }
 pretty_assertions = { workspace = true }
 frame-metadata = { workspace = true }
+
+[package.metadata.docs.rs]
+defalt-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[package.metadata.playground]
+defalt-features = true

codegen/src/lib.rs

@@ -7,6 +7,7 @@
 //! be used directly if preferable.
 
 #![deny(unused_crate_dependencies, missing_docs)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 mod api;
 mod ir;
@@ -18,6 +19,7 @@ pub mod error;
 // macro and CLI tool, so they only live here because this is a common
 // crate that both depend on.
 #[cfg(feature = "fetch-metadata")]
+#[cfg_attr(docsrs, doc(cfg(feature = "fetch-metadata")))]
 pub mod fetch_metadata;
 
 #[cfg(feature = "web")]

lightclient/Cargo.toml

@@ -80,3 +80,10 @@ pin-project = { workspace = true, optional = true }
 
 # Included if "web" feature is enabled, to enable its js feature.
 getrandom = { workspace = true, optional = true }
+
+[package.metadata.docs.rs]
+defalt-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[package.metadata.playground]
+defalt-features = true

lightclient/src/lib.rs

@@ -10,6 +10,8 @@
 //!
 //! This leverages the smoldot crate to connect to the chain.
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[cfg(any(
     all(feature = "web", feature = "native"),
     not(any(feature = "web", feature = "native"))
@@ -35,6 +37,7 @@ pub mod smoldot {
     };
 
     #[cfg(feature = "native")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "native")))]
     pub use smoldot_light::platform::default::DefaultPlatform;
 }
 

signer/Cargo.toml

@@ -58,3 +58,10 @@ sp-keyring = { workspace = true }
 
 [package.metadata.cargo-machete]
 ignored = ["getrandom"]
+
+[package.metadata.docs.rs]
+defalt-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[package.metadata.playground]
+defalt-features = true

signer/src/lib.rs

@@ -13,16 +13,20 @@
 //! Enable the `subxt` feature to enable use of this [`sr25519::Keypair`] in signing
 //! subxt transactions for chains supporting sr25519 signatures.
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[macro_use]
 mod utils;
 mod crypto;
 
 // An sr25519 key pair implementation.
 #[cfg(feature = "sr25519")]
+#[cfg_attr(docsrs, doc(cfg(feature = "sr25519")))]
 pub mod sr25519;
 
 // An ecdsa key pair implementation.
 #[cfg(feature = "ecdsa")]
+#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
 pub mod ecdsa;
 
 // Re-export useful bits and pieces for generating a Pair from a phrase,

signer/src/sr25519.rs

@@ -245,6 +245,7 @@ pub mod dev {
 // Make `Keypair` usable to sign transactions in Subxt. This is optional so that
 // `subxt-signer` can be used entirely independently of Subxt.
 #[cfg(feature = "subxt")]
+#[cfg_attr(docsrs, doc(cfg(feature = "subxt")))]
 mod subxt_compat {
     use super::*;
 

subxt/Cargo.toml

@@ -122,3 +122,10 @@ required-features = ["unstable-light-client", "jsonrpsee"]
 name = "light_client_parachains"
 path = "examples/light_client_parachains.rs"
 required-features = ["unstable-light-client", "jsonrpsee", "native"]
+
+[package.metadata.docs.rs]
+defalt-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[package.metadata.playground]
+defalt-features = true

subxt/src/backend/rpc/mod.rs

@@ -56,8 +56,9 @@
 // with other file names for their types.
 #![allow(clippy::module_inception)]
 
-#[cfg(feature = "jsonrpsee")]
-mod jsonrpsee_impl;
+crate::macros::cfg_jsonrpsee! {
+    mod jsonrpsee_impl;
+}
 
 mod rpc_client;
 mod rpc_client_t;

subxt/src/backend/rpc/rpc_client.rs

@@ -19,6 +19,7 @@ pub struct RpcClient {
 
 impl RpcClient {
     #[cfg(feature = "jsonrpsee")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "jsonrpsee")))]
     /// Create a default RPC client pointed at some URL, currently based on [`jsonrpsee`].
     pub async fn from_url<U: AsRef<str>>(url: U) -> Result<Self, Error> {
         let client = jsonrpsee_helpers::client(url.as_ref())

subxt/src/client/light_client/builder.rs

@@ -5,6 +5,7 @@
 use super::{rpc::LightClientRpc, LightClient, LightClientError};
 use crate::backend::rpc::RpcClient;
 use crate::client::RawLightClient;
+use crate::macros::cfg_jsonrpsee;
 use crate::{config::Config, error::Error, OnlineClient};
 use std::num::NonZeroU32;
 use subxt_lightclient::{smoldot, AddedChain};
@@ -100,6 +101,7 @@ impl<T: Config> LightClientBuilder<T> {
     /// If smoldot panics, then the promise created will be leaked. For more details, see
     /// https://docs.rs/wasm-bindgen-futures/latest/wasm_bindgen_futures/fn.future_to_promise.html.
     #[cfg(feature = "jsonrpsee")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "jsonrpsee")))]
     pub async fn build_from_url<Url: AsRef<str>>(self, url: Url) -> Result<LightClient<T>, Error> {
         let chain_spec = fetch_url(url.as_ref()).await?;
 
@@ -244,34 +246,35 @@ async fn fetch_url(url: impl AsRef<str>) -> Result<serde_json::Value, Error> {
         .map_err(|err| Error::Rpc(crate::error::RpcError::ClientError(Box::new(err))))
 }
 
-#[cfg(all(feature = "jsonrpsee", feature = "native"))]
-mod jsonrpsee_helpers {
-    use crate::error::{Error, LightClientError};
-    pub use jsonrpsee::{
-        client_transport::ws::{Receiver, Sender, Url, WsTransportClientBuilder},
-        core::client::Client,
-    };
+cfg_jsonrpsee_native! {
+    mod jsonrpsee_helpers {
+        use crate::error::{Error, LightClientError};
+        pub use jsonrpsee::{
+            client_transport::ws::{Receiver, Sender, Url, WsTransportClientBuilder},
+            core::client::Client,
+        };
 
-    /// Build WS RPC client from URL
-    pub async fn client(url: &str) -> Result<Client, Error> {
-        let url = Url::parse(url).map_err(|_| Error::LightClient(LightClientError::InvalidUrl))?;
+        /// Build WS RPC client from URL
+        pub async fn client(url: &str) -> Result<Client, Error> {
+            let url = Url::parse(url).map_err(|_| Error::LightClient(LightClientError::InvalidUrl))?;
 
-        if url.scheme() != "ws" && url.scheme() != "wss" {
-            return Err(Error::LightClient(LightClientError::InvalidScheme));
-        }
+            if url.scheme() != "ws" && url.scheme() != "wss" {
+                return Err(Error::LightClient(LightClientError::InvalidScheme));
+            }
 
-        let (sender, receiver) = ws_transport(url).await?;
+            let (sender, receiver) = ws_transport(url).await?;
 
-        Ok(Client::builder()
+            Ok(Client::builder()
             .max_buffer_capacity_per_subscription(4096)
             .build_with_tokio(sender, receiver))
-    }
+        }
 
-    async fn ws_transport(url: Url) -> Result<(Sender, Receiver), Error> {
-        WsTransportClientBuilder::default()
-            .build(url)
-            .await
-            .map_err(|_| Error::LightClient(LightClientError::Handshake))
+        async fn ws_transport(url: Url) -> Result<(Sender, Receiver), Error> {
+            WsTransportClientBuilder::default()
+                .build(url)
+                .await
+                .map_err(|_| Error::LightClient(LightClientError::Handshake))
+        }
     }
 }
 

subxt/src/client/mod.rs

@@ -11,15 +11,15 @@
 mod offline_client;
 mod online_client;
 
-#[cfg(feature = "unstable-light-client")]
-mod light_client;
+crate::macros::cfg_unstable_light_client! {
+    mod light_client;
+
+    pub use light_client::{
+        LightClient, LightClientBuilder, LightClientError, RawLightClient, RawLightClientBuilder,
+    };
+}
 
 pub use offline_client::{OfflineClient, OfflineClientT};
 pub use online_client::{
     ClientRuntimeUpdater, OnlineClient, OnlineClientT, RuntimeUpdaterStream, Update, UpgradeError,
 };
-
-#[cfg(feature = "unstable-light-client")]
-pub use light_client::{
-    LightClient, LightClientBuilder, LightClientError, RawLightClient, RawLightClientBuilder,
-};

subxt/src/client/online_client.rs

@@ -56,6 +56,7 @@ impl<T: Config> std::fmt::Debug for OnlineClient<T> {
 
 // The default constructors assume Jsonrpsee.
 #[cfg(feature = "jsonrpsee")]
+#[cfg_attr(docsrs, doc(cfg(feature = "jsonrpsee")))]
 impl<T: Config> OnlineClient<T> {
     /// Construct a new [`OnlineClient`] using default settings which
     /// point to a locally running node on `ws://127.0.0.1:9944`.

subxt/src/config/mod.rs

@@ -15,6 +15,7 @@ pub mod polkadot;
 pub mod signed_extensions;
 pub mod substrate;
 
+use crate::macros::cfg_substrate_compat;
 use codec::{Decode, Encode};
 use core::fmt::Debug;
 use scale_decode::DecodeAsType;
@@ -125,28 +126,29 @@ pub trait Header: Sized + Encode + Decode {
     }
 }
 
-/// implement subxt's Hasher and Header traits for some substrate structs
-#[cfg(feature = "substrate-compat")]
-mod substrate_impls {
-    use super::*;
-
-    impl<T: sp_runtime::traits::Header> Header for T
-    where
-        <T as sp_runtime::traits::Header>::Number: Into<u64>,
-    {
-        type Number = T::Number;
-        type Hasher = T::Hashing;
-
-        fn number(&self) -> Self::Number {
-            *self.number()
+cfg_substrate_compat! {
+    /// implement subxt's Hasher and Header traits for some substrate structs
+    mod substrate_impls {
+        use super::*;
+
+        impl<T: sp_runtime::traits::Header> Header for T
+        where
+            <T as sp_runtime::traits::Header>::Number: Into<u64>,
+        {
+            type Number = T::Number;
+            type Hasher = T::Hashing;
+
+            fn number(&self) -> Self::Number {
+                *self.number()
+            }
         }
-    }
 
-    impl<T: sp_runtime::traits::Hash> Hasher for T {
-        type Output = T::Output;
+        impl<T: sp_runtime::traits::Hash> Hasher for T {
+            type Output = T::Output;
 
-        fn hash(s: &[u8]) -> Self::Output {
-            <T as sp_runtime::traits::Hash>::hash(s)
+            fn hash(s: &[u8]) -> Self::Output {
+                <T as sp_runtime::traits::Hash>::hash(s)
+            }
         }
     }
 }

subxt/src/error/mod.rs

@@ -8,8 +8,9 @@ mod dispatch_error;
 
 use core::fmt::Debug;
 
-#[cfg(feature = "unstable-light-client")]
-pub use crate::client::LightClientError;
+crate::macros::cfg_unstable_light_client! {
+    pub use crate::client::LightClientError;
+}
 
 // Re-export dispatch error types:
 pub use dispatch_error::{
@@ -73,6 +74,7 @@ pub enum Error {
     Unknown(Vec<u8>),
     /// Light client error.
     #[cfg(feature = "unstable-light-client")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-light-client")))]
     #[error("An error occurred but it could not be decoded: {0}")]
     LightClient(#[from] LightClientError),
     /// Other error.

subxt/src/lib.rs

@@ -10,6 +10,8 @@
 //!
 //! Take a look at [the Subxt guide](book) to learn more about how to use Subxt.
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[cfg(any(
     all(feature = "web", feature = "native"),
     not(any(feature = "web", feature = "native"))
@@ -55,6 +57,10 @@ pub mod storage;
 pub mod tx;
 pub mod utils;
 
+// Macros useful below, but not to be exposed outside of the crate.
+#[macro_use]
+mod macros;
+
 // Expose a few of the most common types at root,
 // but leave most types behind their respective modules.
 pub use crate::{
@@ -73,10 +79,11 @@ pub mod ext {
     pub use scale_decode;
     pub use scale_encode;
     pub use scale_value;
-    #[cfg(feature = "substrate-compat")]
-    pub use sp_core;
-    #[cfg(feature = "substrate-compat")]
-    pub use sp_runtime;
+
+    cfg_substrate_compat! {
+        pub use sp_runtime;
+        pub use sp_core;
+    }
 }
 
 /// Generate a strongly typed API for interacting with a Substrate runtime from its metadata.

subxt/src/macros.rs

@@ -0,0 +1,49 @@
+// 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.
+
+macro_rules! cfg_feature {
+	($feature:literal, $($item:item)*) => {
+		$(
+			#[cfg(feature = $feature)]
+			#[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
+			$item
+		)*
+	}
+}
+
+macro_rules! cfg_substrate_compat {
+	($($item:item)*) => {
+		crate::macros::cfg_feature!("substrate-compat", $($item)*);
+	};
+}
+
+macro_rules! cfg_unstable_light_client {
+	($($item:item)*) => {
+		crate::macros::cfg_feature!("unstable-light-client", $($item)*);
+	};
+}
+
+macro_rules! cfg_jsonrpsee {
+	($($item:item)*) => {
+		crate::macros::cfg_feature!("jsonrpsee", $($item)*);
+	};
+}
+
+#[allow(unused)]
+macro_rules! cfg_jsonrpsee_native {
+	($($item:item)*) => {
+		$(
+			#[cfg(all(feature = "jsonrpsee", feature = "native"))]
+			#[cfg_attr(docsrs, doc(cfg(all(feature = "jsonrpsee", feature = "native"))))]
+			$item
+		)*
+	}
+}
+
+pub(crate) use cfg_feature;
+pub(crate) use cfg_jsonrpsee;
+#[allow(unused)]
+pub(crate) use cfg_jsonrpsee_native;
+pub(crate) use cfg_substrate_compat;
+pub(crate) use cfg_unstable_light_client;