Document feature flags and scrape examples

.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"

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",
+]

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)]