tawasuyu/taffy

* 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
  <https://doc.rust-lang.org/rustdoc/unstable-features.html#doc_auto_cfg-automatically-generate-doccfg>
  for more information.
- Automatically scrape example code into the documentation using the
  unstable rustdoc-scrape-examples feature. See
  <https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html> 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
```

* Check the new rustdoc options in CI and tweak wording

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