diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index 246da2cd68c6..20414505210c 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -15,55 +15,91 @@ workspace = true [dependencies] # Needed for all FRAME-based code -parity-scale-codec = { version = "3.0.0", default-features = false } -scale-info = { version = "2.6.0", default-features = false } -frame = { path = "../../substrate/frame", features = ["experimental", "runtime"] } -pallet-examples = { path = "../../substrate/frame/examples" } -pallet-default-config-example = { path = "../../substrate/frame/examples/default-config" } +parity-scale-codec = { version = "3.0.0", default-features = false, optional = true } +scale-info = { version = "2.6.0", default-features = false, optional = true } +frame = { path = "../../substrate/frame", features = ["experimental", "runtime"], optional = true } +pallet-examples = { path = "../../substrate/frame/examples", optional = true } +pallet-default-config-example = { path = "../../substrate/frame/examples/default-config", optional = true } # How we build docs in rust-docs -simple-mermaid = { git = "https://github.com/kianenigma/simple-mermaid.git", rev = "e48b187bcfd5cc75111acd9d241f1bd36604344b" } -docify = "0.2.6" +simple-mermaid = { git = "https://github.com/kianenigma/simple-mermaid.git", rev = "e48b187bcfd5cc75111acd9d241f1bd36604344b" , optional = true } +docify = { version = "0.2.6", optional = true } + # Polkadot SDK deps, typically all should only be in scope such that we can link to their doc item. -node-cli = { package = "staging-node-cli", path = "../../substrate/bin/node/cli" } -kitchensink-runtime = { path = "../../substrate/bin/node/runtime" } -chain-spec-builder = { package = "staging-chain-spec-builder", path = "../../substrate/bin/utils/chain-spec-builder" } -subkey = { path = "../../substrate/bin/utils/subkey" } +node-cli = { package = "staging-node-cli", path = "../../substrate/bin/node/cli", optional = true } +kitchensink-runtime = { path = "../../substrate/bin/node/runtime", optional = true } +chain-spec-builder = { package = "staging-chain-spec-builder", path = "../../substrate/bin/utils/chain-spec-builder", optional = true } +subkey = { path = "../../substrate/bin/utils/subkey", optional = true } # Substrate -sc-network = { path = "../../substrate/client/network" } -sc-rpc-api = { path = "../../substrate/client/rpc-api" } -sc-rpc = { path = "../../substrate/client/rpc" } -sc-client-db = { path = "../../substrate/client/db" } -sc-cli = { path = "../../substrate/client/cli" } -sc-consensus-aura = { path = "../../substrate/client/consensus/aura" } -sc-consensus-babe = { path = "../../substrate/client/consensus/babe" } -sc-consensus-grandpa = { path = "../../substrate/client/consensus/grandpa" } -sc-consensus-beefy = { path = "../../substrate/client/consensus/beefy" } -sc-consensus-manual-seal = { path = "../../substrate/client/consensus/manual-seal" } -sc-consensus-pow = { path = "../../substrate/client/consensus/pow" } -substrate-wasm-builder = { path = "../../substrate/utils/wasm-builder" } +sc-network = { path = "../../substrate/client/network", optional = true } +sc-rpc-api = { path = "../../substrate/client/rpc-api", optional = true } +sc-rpc = { path = "../../substrate/client/rpc", optional = true } +sc-client-db = { path = "../../substrate/client/db", optional = true } +sc-cli = { path = "../../substrate/client/cli", optional = true } +sc-consensus-aura = { path = "../../substrate/client/consensus/aura", optional = true } +sc-consensus-babe = { path = "../../substrate/client/consensus/babe", optional = true } +sc-consensus-grandpa = { path = "../../substrate/client/consensus/grandpa", optional = true } +sc-consensus-beefy = { path = "../../substrate/client/consensus/beefy", optional = true } +sc-consensus-manual-seal = { path = "../../substrate/client/consensus/manual-seal", optional = true } +sc-consensus-pow = { path = "../../substrate/client/consensus/pow", optional = true } +substrate-wasm-builder = { path = "../../substrate/utils/wasm-builder", optional = true } # Cumulus -cumulus-pallet-aura-ext = { path = "../../cumulus/pallets/aura-ext" } +cumulus-pallet-aura-ext = { path = "../../cumulus/pallets/aura-ext", optional = true } cumulus-pallet-parachain-system = { path = "../../cumulus/pallets/parachain-system", features = [ "parameterized-consensus-hook", -] } -parachain-info = { package = "staging-parachain-info", path = "../../cumulus/parachains/pallets/parachain-info" } -pallet-aura = { path = "../../substrate/frame/aura", default-features = false } -pallet-timestamp = { path = "../../substrate/frame/timestamp" } +], optional = true } +parachain-info = { package = "staging-parachain-info", path = "../../cumulus/parachains/pallets/parachain-info", optional = true } +pallet-aura = { path = "../../substrate/frame/aura", default-features = false, optional = true } +pallet-timestamp = { path = "../../substrate/frame/timestamp", optional = true } # Primitives -sp-io = { path = "../../substrate/primitives/io" } -sp-api = { path = "../../substrate/primitives/api" } -sp-core = { path = "../../substrate/primitives/core" } -sp-keyring = { path = "../../substrate/primitives/keyring" } -sp-runtime = { path = "../../substrate/primitives/runtime" } - -[dev-dependencies] -parity-scale-codec = "3.6.5" -scale-info = "2.9.0" +sp-io = { path = "../../substrate/primitives/io", optional = true } +sp-api = { path = "../../substrate/primitives/api", optional = true } +sp-core = { path = "../../substrate/primitives/core", optional = true } +sp-keyring = { path = "../../substrate/primitives/keyring", optional = true } +sp-runtime = { path = "../../substrate/primitives/runtime", optional = true } [features] +default = ["min-docs", "docs-build-deps"] +min-docs = [ + "simple-mermaid", + "docify", +] +docs-build-deps = [ + "sp-io", + "parity-scale-codec", + "scale-info", + "frame", + "pallet-examples", + "pallet-default-config-example", + "node-cli", + "kitchensink-runtime", + "chain-spec-builder", + "subkey", + "sc-network", + "sc-rpc-api", + "sc-rpc", + "sc-client-db", + "sc-cli", + "sc-consensus-aura", + "sc-consensus-babe", + "sc-consensus-grandpa", + "sc-consensus-beefy", + "sc-consensus-manual-seal", + "sc-consensus-pow", + "substrate-wasm-builder", + "cumulus-pallet-aura-ext", + "cumulus-pallet-parachain-system", + "parachain-info", + "pallet-aura", + "pallet-timestamp", + "sp-io", + "sp-api", + "sp-core", + "sp-keyring", + "sp-runtime", +] experimental = ["pallet-aura/experimental"] diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 24eada44a83a..9fd5cfa05cd4 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -299,6 +299,7 @@ //! - Learn more about the individual pallet items/macros, such as event and errors and call, in //! [`frame::pallet_macros`]. +#[cfg(feature = "docs-build-deps")] #[docify::export] #[frame::pallet(dev_mode)] pub mod shell_pallet { @@ -311,6 +312,7 @@ pub mod shell_pallet { pub struct Pallet(_); } +#[cfg(feature = "docs-build-deps")] #[frame::pallet(dev_mode)] pub mod pallet { use frame::prelude::*; @@ -630,6 +632,7 @@ pub mod pallet { } } +#[cfg(feature = "docs-build-deps")] #[frame::pallet(dev_mode)] pub mod pallet_v2 { use super::pallet::Balance; diff --git a/docs/sdk/src/lib.rs b/docs/sdk/src/lib.rs index 075d9ddaffe5..44b720acdaaf 100644 --- a/docs/sdk/src/lib.rs +++ b/docs/sdk/src/lib.rs @@ -23,8 +23,12 @@ //! //! This section paints a picture over the high-level information architecture of this crate. #![doc = simple_mermaid::mermaid!("../../mermaid/IA.mmd")] -#![warn(rustdoc::broken_intra_doc_links)] -#![warn(rustdoc::private_intra_doc_links)] +#![deny(rustdoc::broken_intra_doc_links)] +#![deny(rustdoc::private_intra_doc_links)] +// Overide above deny if no deps are being built +#![cfg(not(feature = "docs-build-deps"))] +#![allow(rustdoc::broken_intra_doc_links)] +#![allow(rustdoc::private_intra_doc_links)] /// Meta information about this crate, how it is built, what principles dictates its evolution and /// how one can contribute to it. diff --git a/docs/sdk/src/meta_contributing.rs b/docs/sdk/src/meta_contributing.rs index bff475f8e6bf..4511eb06dd02 100644 --- a/docs/sdk/src/meta_contributing.rs +++ b/docs/sdk/src/meta_contributing.rs @@ -134,14 +134,18 @@ //! //! ## How to Develop Locally //! -//! To view the docs specific [`crate`] locally for development, including the correct HTML headers -//! injected, run: +//! To expedite documentation development and view _only_ the docs specific [`crate`] locally for +//! development, including the correct HTML headers injected, run: //! //! ```sh +//! # (Fastest) HTML ONLY - Only build the documentation crate, with MINIMAL code compilation. +//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/toc.html" cargo doc -p polkadot-sdk-docs --no-default-features -F min-docs --no-deps --open +//! +//! # SDK Docs only - Minimal build - Only build the documentation crate, including code compilation for examples. //! SKIP_WASM_BUILD=1 RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/toc.html" cargo doc -p polkadot-sdk-docs --no-deps --open -//! ``` //! -//! If even faster build time for docs is needed, you can temporarily remove most of the -//! substrate/cumulus dependencies that are only used for linking purposes. +//! # All docs, with external deps +//! SKIP_WASM_BUILD=1 RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/toc.html" cargo doc --no-deps --open +//! ``` //! //! For more on local development, see [`crate::reference_docs::development_environment_advice`]. diff --git a/docs/sdk/src/polkadot_sdk/cumulus.rs b/docs/sdk/src/polkadot_sdk/cumulus.rs index 07a48c92d807..b55640ee9451 100644 --- a/docs/sdk/src/polkadot_sdk/cumulus.rs +++ b/docs/sdk/src/polkadot_sdk/cumulus.rs @@ -42,7 +42,6 @@ //! //! [FRAME]: crate::polkadot_sdk::frame_runtime -#![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] #[cfg(test)] diff --git a/docs/sdk/src/reference_docs/extrinsic_encoding.rs b/docs/sdk/src/reference_docs/extrinsic_encoding.rs index 89c7cfe983c1..13700ba11d03 100644 --- a/docs/sdk/src/reference_docs/extrinsic_encoding.rs +++ b/docs/sdk/src/reference_docs/extrinsic_encoding.rs @@ -189,6 +189,7 @@ //! as follows: #![doc = docify::embed!("./src/reference_docs/extrinsic_encoding.rs", encoding_example)] +#[cfg(feature = "docs-build-deps")] #[docify::export] pub mod call_data { use parity_scale_codec::{Decode, Encode}; @@ -220,6 +221,7 @@ pub mod call_data { } } +#[cfg(feature = "docs-build-deps")] #[docify::export] pub mod encoding_example { use super::call_data::{Call, PalletACall}; diff --git a/docs/sdk/src/reference_docs/signed_extensions.rs b/docs/sdk/src/reference_docs/signed_extensions.rs index 28b1426536bc..9c13417e30e6 100644 --- a/docs/sdk/src/reference_docs/signed_extensions.rs +++ b/docs/sdk/src/reference_docs/signed_extensions.rs @@ -6,6 +6,7 @@ //! Defining a couple of very simple signed extensions looks like the following: #![doc = docify::embed!("./src/reference_docs/signed_extensions.rs", signed_extensions_example)] +#[cfg(feature = "docs-build-deps")] #[docify::export] pub mod signed_extensions_example { use parity_scale_codec::{Decode, Encode}; diff --git a/docs/sdk/src/reference_docs/trait_based_programming.rs b/docs/sdk/src/reference_docs/trait_based_programming.rs index ace313880707..61afc2fbd556 100644 --- a/docs/sdk/src/reference_docs/trait_based_programming.rs +++ b/docs/sdk/src/reference_docs/trait_based_programming.rs @@ -113,8 +113,10 @@ //! - #![allow(unused)] +#[cfg(feature = "docs-build-deps")] use frame::traits::Get; +#[cfg(feature = "docs-build-deps")] #[docify::export] mod basic { struct Pallet; @@ -130,6 +132,7 @@ mod basic { } } +#[cfg(feature = "docs-build-deps")] #[docify::export] mod generic { use super::*; @@ -151,6 +154,7 @@ mod generic { } } +#[cfg(feature = "docs-build-deps")] #[docify::export] mod trait_based { use super::*; @@ -170,6 +174,7 @@ mod trait_based { } } +#[cfg(feature = "docs-build-deps")] #[docify::export] mod with_system { use super::*; @@ -192,6 +197,7 @@ mod with_system { } } +#[cfg(feature = "docs-build-deps")] #[docify::export] mod fully_qualified { use super::with_system::*; @@ -200,6 +206,7 @@ mod fully_qualified { type AccountIdOf = ::AccountId; } +#[cfg(feature = "docs-build-deps")] #[docify::export] mod fully_qualified_complicated { use super::with_system::*;