Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature gate to minimize polkadot-sdk-docs build time #2937

Closed
wants to merge 6 commits into from
Closed

Feature gate to minimize polkadot-sdk-docs build time #2937

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c3c8513
move all docs deps to feature gate in cargo.toml
nuke-web3 Jan 15, 2024
29824b5
feature gate building anything not needed for sdk docs HTML
nuke-web3 Jan 15, 2024
8b476f8
feature gate all docs, skip deny lint if only HTML generation
nuke-web3 Jan 15, 2024
643733a
working MVP of feature gate on minimal HTML only docs and full compil…
nuke-web3 Jan 15, 2024
94875f4
feature gate correct on lint
nuke-web3 Jan 15, 2024
acfabc8
fmt
nuke-web3 Jan 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 73 additions & 37 deletions docs/sdk/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
3 changes: 3 additions & 0 deletions docs/sdk/src/guides/your_first_pallet/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -311,6 +312,7 @@ pub mod shell_pallet {
pub struct Pallet<T>(_);
}

#[cfg(feature = "docs-build-deps")]
#[frame::pallet(dev_mode)]
pub mod pallet {
use frame::prelude::*;
Expand Down Expand Up @@ -630,6 +632,7 @@ pub mod pallet {
}
}

#[cfg(feature = "docs-build-deps")]
#[frame::pallet(dev_mode)]
pub mod pallet_v2 {
use super::pallet::Balance;
Expand Down
8 changes: 6 additions & 2 deletions docs/sdk/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
14 changes: 9 additions & 5 deletions docs/sdk/src/meta_contributing.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the command suggested to get the minimal docs build. I did try this again on present master, and what I was experiencing was what I think was very long linking times in the stage of building the full kitchensink runtime and node... I can't seem to reproduce now, so I agree this extra complexity isn't worth it to get fast HTML output to inspect while doing docs dev.

//! ```
//!
//! 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`].
1 change: 0 additions & 1 deletion docs/sdk/src/polkadot_sdk/cumulus.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@
//!
//! [FRAME]: crate::polkadot_sdk::frame_runtime

#![deny(rustdoc::broken_intra_doc_links)]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unclear if this lint must live here, if so it may need to be feature gated as it breaks the minimal docs build

#![deny(rustdoc::private_intra_doc_links)]

#[cfg(test)]
Expand Down
2 changes: 2 additions & 0 deletions docs/sdk/src/reference_docs/extrinsic_encoding.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down Expand Up @@ -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};
Expand Down
1 change: 1 addition & 0 deletions docs/sdk/src/reference_docs/signed_extensions.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down
7 changes: 7 additions & 0 deletions docs/sdk/src/reference_docs/trait_based_programming.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,10 @@
//! - <https://substrate.stackexchange.com/questions/2228/type-casting-to-trait-t-as-config>
#![allow(unused)]

#[cfg(feature = "docs-build-deps")]
use frame::traits::Get;

#[cfg(feature = "docs-build-deps")]
#[docify::export]
mod basic {
struct Pallet;
Expand All @@ -130,6 +132,7 @@ mod basic {
}
}

#[cfg(feature = "docs-build-deps")]
#[docify::export]
mod generic {
use super::*;
Expand All @@ -151,6 +154,7 @@ mod generic {
}
}

#[cfg(feature = "docs-build-deps")]
#[docify::export]
mod trait_based {
use super::*;
Expand All @@ -170,6 +174,7 @@ mod trait_based {
}
}

#[cfg(feature = "docs-build-deps")]
#[docify::export]
mod with_system {
use super::*;
Expand All @@ -192,6 +197,7 @@ mod with_system {
}
}

#[cfg(feature = "docs-build-deps")]
#[docify::export]
mod fully_qualified {
use super::with_system::*;
Expand All @@ -200,6 +206,7 @@ mod fully_qualified {
type AccountIdOf<T> = <T as SystemConfig>::AccountId;
}

#[cfg(feature = "docs-build-deps")]
#[docify::export]
mod fully_qualified_complicated {
use super::with_system::*;
Expand Down