From 882d0b41c418fc7aa49716878f844fab25e670d1 Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Thu, 27 Jun 2024 14:41:46 -0700 Subject: [PATCH 1/2] Document feature flags - Use [document-features](https://crates.io/crates/document-features) crate to automatically add documentation about the features to the crate documentation at the crate level. - Use the doc_auto_cfg feature to automatically add documentation to every item that requires a feature flag to be enabled. This is behind a docsrs feature flag as it can only be enabled using the nightly toolchain and this allows the documentation to be built with the stable toolchain when the feature is not enabled. See for more information. - Automatically scrape example code into the documentation using the unstable rustdoc-scrape-examples feature. See for more information. To test this change, run: ```shell RUSTDOCFLAGS="--cfg docsrs" \ cargo +nightly doc \ -Zunstable-options -Zrustdoc-scrape-examples \ --all-features --no-deps --open ``` --- Cargo.toml | 64 +++++++++++++++++++++++++++++++++++++++--------------- src/lib.rs | 4 ++++ 2 files changed, 50 insertions(+), 18 deletions(-) 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..ff57550b4 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 +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] +// document required feature flags on each item (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)] From 93f5865615ad5d66c357df5488d00e9f6a0a51a4 Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Fri, 28 Jun 2024 23:23:01 -0700 Subject: [PATCH 2/2] Check the new rustdoc options in CI and tweak wording --- .github/workflows/ci.yml | 16 ++++++++++------ src/lib.rs | 4 ++-- 2 files changed, 12 insertions(+), 8 deletions(-) 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/src/lib.rs b/src/lib.rs index ff57550b4..fa163db3c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -57,9 +57,9 @@ //! - [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 +// document the feature flags for the crate by extracting the comments from Cargo.toml #![cfg_attr(feature = "document-features", doc = document_features::document_features!())] -// document required feature flags on each item (gated by docsrs flag as this requires the nightly toolchain) +// 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)]