diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a7943bb6f..6cc81aa7a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,6 @@ env: CARGO_REGISTRIES_CRATES_IO_PROTOCOL: "sparse" jobs: - # MSRV check. # Taffy only guarantees "latest stable". However we have this check here to ensure that we advertise # our MSRV. We also make an effort not to increase MSRV in patch versions of Taffy. @@ -161,16 +160,21 @@ jobs: components: clippy - run: cargo +nightly clippy --workspace -- -D warnings + # Run rustdoc with the `docsrs` cfg to ensure that the documentation is compatible with docs.rs. + # This enables the doc_auto_cfg feature, which requires the nightly toolchain. + # Also checks that the examples can be scraped. doc: name: Documentation runs-on: ubuntu-latest + env: + RUSTDOCFLAGS: "--cfg docsrs" steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@master with: - toolchain: stable + toolchain: nightly components: clippy - - run: cargo doc + - run: cargo +nightly doc -Zunstable-options -Zrustdoc-scrape-examples --all-features --no-deps markdownlint: name: Markdown Lint @@ -180,7 +184,7 @@ jobs: - name: Run Markdown Lint uses: DavidAnson/markdownlint-cli2-action@v16 with: - globs: '**/*.md' + globs: "**/*.md" fixture-format: name: Test Fixture Formatting @@ -207,7 +211,7 @@ jobs: - run: cargo xbench --no-run name: Build benchmarks env: - RUSTFLAGS: "-C opt-level=0" + RUSTFLAGS: "-C opt-level=0" benchmarks-with-yoga: name: Build Benchmarks (w/ yoga) @@ -218,4 +222,4 @@ jobs: - run: cargo xbench --no-run --features yoga name: Build benchmarks (w/yoga) env: - RUSTFLAGS: "-C opt-level=0" + RUSTFLAGS: "-C opt-level=0" diff --git a/Cargo.toml b/Cargo.toml index 76eedbbb9..294c0c118 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,43 +17,61 @@ license = "MIT" [dependencies] arrayvec = { version = "0.7", default-features = false } +document-features = { version = "0.2.7", optional = true } num-traits = { version = "0.2", default-features = false } -serde = { version = "1.0", default-features = false, optional = true, features = ["serde_derive"] } +serde = { version = "1.0", default-features = false, optional = true, features = [ + "serde_derive", +] } slotmap = { version = "1.0.6", default-features = false, optional = true } grid = { version = "0.14.0", default-features = false, optional = true } -### FEATURES ################################################################# +[package.metadata.docs.rs] +# To test all the documentation related features, run: +# RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc -Zunstable-options -Zrustdoc-scrape-examples --all-features --no-deps --open -[features] -default = ["std", "taffy_tree", "flexbox", "grid", "block_layout", "content_size"] +all-features = true +# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html +cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] +rustdoc-args = ["--cfg", "docsrs"] -### Algorithms +[features] +default = [ + "std", + "taffy_tree", + "flexbox", + "grid", + "block_layout", + "content_size", +] +#! ## Feature Flags +#! +#! ### Algorithms -# Enables the Block layout algorithm +## Enables the Block layout algorithm. See [`compute_block_layout`](crate::compute_block_layout). block_layout = [] -# Enables the Flexbox layout algorithm +## Enables the Flexbox layout algorithm. See [`compute_flexbox_layout`](crate::compute_flexbox_layout). flexbox = [] -# Enables the CSS Grid layout algorithm +## Enables the CSS Grid layout algorithm. See [`compute_grid_layout`](crate::compute_grid_layout). grid = ["alloc", "dep:grid"] -# Causes all algorithms to compute and output a content size for each node +## Causes all algorithms to compute and output a content size for each node content_size = [] -### Taffy Tree +#! ### Taffy Tree -# Enable the built-in Taffy node tree +## Enable the built-in Taffy node tree. See [`TaffyTree`](crate::TaffyTree). taffy_tree = ["dep:slotmap"] -### Other +#! ### Other -# Add serde derives to Style structs +## Add [`serde`] derives to Style structs serde = ["dep:serde"] -# Allow Taffy to depend on the standard library +## Allow Taffy to depend on the [`Rust Standard Library`](std) std = ["num-traits/std", "grid?/std", "serde?/std", "slotmap?/std"] -# Allow Taffy to depend on the alloc library +## Allow Taffy to depend on the alloc library alloc = ["serde?/alloc"] -# Internal feature for debugging +## Internal feature for debugging debug = ["std"] -# Internal feature for profiling +## Internal feature for profiling profile = ["std"] [dev-dependencies] @@ -72,5 +90,15 @@ name = "dummy_benchmark" path = "benches/dummy_benchmark.rs" harness = false +[[example]] +name = "basic" +# This causes all the examples to be scraped for documentation, not just the basic example +doc-scrape-examples = true + [workspace] -members = ["scripts/gentest", "scripts/format-fixtures", "scripts/import-yoga-tests", "benches"] +members = [ + "scripts/gentest", + "scripts/format-fixtures", + "scripts/import-yoga-tests", + "benches", +] diff --git a/src/lib.rs b/src/lib.rs index f95d4c41c..fa163db3c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -57,6 +57,10 @@ //! - [custom_tree_owned_partial](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_owned_partial.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers. //! - [custom_tree_owned_unsafe](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_owned_unsafe.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers. +// document the feature flags for the crate by extracting the comments from Cargo.toml +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] +// annotate items with their required features (gated by docsrs flag as this requires the nightly toolchain) +#![cfg_attr(docsrs, feature(doc_auto_cfg))] #![cfg_attr(not(feature = "std"), no_std)] #![deny(unsafe_code)] #![forbid(unsafe_code)]