generate docs for feature gated items (#1332)

* generate docs for feature-gated items on crates.io

* add newline in Cargo.toml

* unify newlines

* fix clippy

* introduce macros for features

* commit missing file

* Update subxt/src/lib.rs

* make it compile

codegen/Cargo.toml

@@ -5,14 +5,12 @@ authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 publish = true
-
 license.workspace = true
 repository.workspace = true
 documentation = "https://docs.rs/subxt-codegen"
 homepage.workspace = true
 description = "Generate an API for interacting with a substrate node from FRAME metadata"
 
-
 [features]
 default = []
 fetch-metadata = ["dep:jsonrpsee", "dep:tokio", "dep:frame-metadata"]
@@ -38,3 +36,10 @@ getrandom = { workspace = true, optional = true }
 
 [dev-dependencies]
 scale-info = { workspace = true, features = ["bit-vec"] }
+
+[package.metadata.docs.rs]
+features = ["fetch-metadata"]
+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;
 pub mod error;
@@ -16,6 +17,7 @@ mod ir;
 // 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

@@ -129,3 +129,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]
+features = ["default", "substrate-compat", "unstable-light-client"]
+rustdoc-args = ["--cfg", "docsrs"]
+
+[package.metadata.playground]
+features = ["default", "substrate-compat", "unstable-light-client"]

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`].
     ///
     /// Errors if an insecure URL is provided. In this case, use [`RpcClient::from_insecure_url`] instead.

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_native, cfg_jsonrpsee_web};
 use crate::utils::validate_url_is_secure;
 use crate::{config::Config, error::Error, OnlineClient};
 use std::num::NonZeroU32;
@@ -101,6 +102,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> {
         validate_url_is_secure(url.as_ref())?;
         self.build_from_insecure_url(url).await
@@ -255,58 +257,60 @@ 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};
-    use tokio_util::compat::Compat;
+cfg_jsonrpsee_native! {
+    mod jsonrpsee_helpers {
+        use crate::error::{Error, LightClientError};
+        use tokio_util::compat::Compat;
 
-    pub use jsonrpsee::{
-        client_transport::ws::{self, EitherStream, Url, WsTransportClientBuilder},
-        core::client::Client,
-    };
+        pub use jsonrpsee::{
+            client_transport::ws::{self, EitherStream, Url, WsTransportClientBuilder},
+            core::client::Client,
+        };
 
-    pub type Sender = ws::Sender<Compat<EitherStream>>;
-    pub type Receiver = ws::Receiver<Compat<EitherStream>>;
+        pub type Sender = ws::Sender<Compat<EitherStream>>;
+        pub type Receiver = ws::Receiver<Compat<EitherStream>>;
 
-    /// 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()
-            .max_buffer_capacity_per_subscription(4096)
-            .build_with_tokio(sender, receiver))
-    }
+                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))
+            }
+        }
 }
 
-#[cfg(all(feature = "jsonrpsee", feature = "web"))]
-mod jsonrpsee_helpers {
-    use crate::error::{Error, LightClientError};
-    pub use jsonrpsee::{
-        client_transport::web,
-        core::client::{Client, ClientBuilder},
-    };
-
-    /// Build web RPC client from URL
-    pub async fn client(url: &str) -> Result<Client, Error> {
-        let (sender, receiver) = web::connect(url)
-            .await
-            .map_err(|_| Error::LightClient(LightClientError::Handshake))?;
-
-        Ok(ClientBuilder::default()
-            .max_buffer_capacity_per_subscription(4096)
-            .build_with_wasm(sender, receiver))
+cfg_jsonrpsee_web! {
+    mod jsonrpsee_helpers {
+        use crate::error::{Error, LightClientError};
+        pub use jsonrpsee::{
+            client_transport::web,
+            core::client::{Client, ClientBuilder},
+        };
+
+        /// Build web RPC client from URL
+        pub async fn client(url: &str) -> Result<Client, Error> {
+            let (sender, receiver) = web::connect(url)
+                .await
+                .map_err(|_| Error::LightClient(LightClientError::Handshake))?;
+
+            Ok(ClientBuilder::default()
+                .max_buffer_capacity_per_subscription(4096)
+                .build_with_wasm(sender, receiver))
+        }
     }
 }

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)
+            }
         }
     }
 }