[embassy-executor] improved documentation

* Feature auto-documentation
* Task arena sizes in a <details> list
* Non-documented comment explaining turbowakers with see-also link

Further improvements:

* Are the task-arena-size-* numbers sizes in bytes? or something else?
* Task arena section could benefit from advice about how to choose a
  suitable size

4 files changed, 81 insertions, 10 deletions

diff --git a/embassy-executor/Cargo.toml b/embassy-executor/Cargo.toml
index 4dcd03b0f..c71452398 100644
--- a/embassy-executor/Cargo.toml
+++ b/embassy-executor/Cargo.toml
@@ -36,6 +36,8 @@ embassy-executor-macros = { version = "0.4.0", path = "../embassy-executor-macro
 embassy-time = { version = "0.2", path = "../embassy-time", optional = true}
 critical-section = "1.1"
 
+document-features = "0.2.7"
+
 # needed for riscv
 # remove when https://github.com/rust-lang/rust/pull/114499 is merged
 portable-atomic = { version = "1.5", optional = true }
@@ -53,66 +55,126 @@ critical-section = { version = "1.1", features = ["std"] }
 
 [features]
 
-# Architecture
+## Enable nightly-only features
+nightly = ["embassy-executor-macros/nightly"]
+
+# Enables turbo wakers, which requires patching core. Not surfaced in the docs by default due to
+# being an complicated advanced and undocumented feature.
+# See: https://github.com/embassy-rs/embassy/pull/1263
+turbowakers = []
+
+## Use timers from `embassy-time`
+integrated-timers = ["dep:embassy-time"]
+
+#! ### Architecture
 _arch = [] # some arch was picked
+## std
 arch-std = ["_arch", "critical-section/std"]
+## Cortex-M
 arch-cortex-m = ["_arch", "dep:cortex-m"]
+## RISC-V 32
 arch-riscv32 = ["_arch", "dep:portable-atomic"]
+## WASM
 arch-wasm = ["_arch", "dep:wasm-bindgen", "dep:js-sys"]
 
-# Enable the thread-mode executor (using WFE/SEV in Cortex-M, WFI in other embedded archs)
+#! ### Executor
+
+## Enable the thread-mode executor (using WFE/SEV in Cortex-M, WFI in other embedded archs)
 executor-thread = []
-# Enable the interrupt-mode executor (available in Cortex-M only)
+## Enable the interrupt-mode executor (available in Cortex-M only)
 executor-interrupt = []
 
-# Enable nightly-only features
-nightly = ["embassy-executor-macros/nightly"]
-
-turbowakers = []
-
-integrated-timers = ["dep:embassy-time"]
+#! ### Task Arena Size
+#! Sets the [task arena](#task-arena) size. Necessary if you’re not using `nightly`.
+#! 
+#! <details>
+#!  <summary>Preconfigured Task Arena Sizes:</summary>
+#! <!-- rustdoc requires the following blank line for the feature list to render correctly! -->
+#! 
 
 # BEGIN AUTOGENERATED CONFIG FEATURES
 # Generated by gen_config.py. DO NOT EDIT.
+## 64
 task-arena-size-64 = []
+## 128
 task-arena-size-128 = []
+## 192
 task-arena-size-192 = []
+## 256
 task-arena-size-256 = []
+## 320
 task-arena-size-320 = []
+## 384
 task-arena-size-384 = []
+## 512
 task-arena-size-512 = []
+## 640
 task-arena-size-640 = []
+## 768
 task-arena-size-768 = []
+## 1024
 task-arena-size-1024 = []
+## 1280
 task-arena-size-1280 = []
+## 1536
 task-arena-size-1536 = []
+## 2048
 task-arena-size-2048 = []
+## 2560
 task-arena-size-2560 = []
+## 3072
 task-arena-size-3072 = []
+## 4096 (default)
 task-arena-size-4096 = [] # Default
+## 5120
 task-arena-size-5120 = []
+## 6144
 task-arena-size-6144 = []
+## 8192
 task-arena-size-8192 = []
+## 10240
 task-arena-size-10240 = []
+## 12288
 task-arena-size-12288 = []
+## 16384
 task-arena-size-16384 = []
+## 20480
 task-arena-size-20480 = []
+## 24576
 task-arena-size-24576 = []
+## 32768
 task-arena-size-32768 = []
+## 40960
 task-arena-size-40960 = []
+## 49152
 task-arena-size-49152 = []
+## 65536
 task-arena-size-65536 = []
+## 81920
 task-arena-size-81920 = []
+## 98304
 task-arena-size-98304 = []
+## 131072
 task-arena-size-131072 = []
+## 163840
 task-arena-size-163840 = []
+## 196608
 task-arena-size-196608 = []
+## 262144
 task-arena-size-262144 = []
+## 327680
 task-arena-size-327680 = []
+## 393216
 task-arena-size-393216 = []
+## 524288
 task-arena-size-524288 = []
+## 655360
 task-arena-size-655360 = []
+## 786432
 task-arena-size-786432 = []
+## 1048576
 task-arena-size-1048576 = []
 
 # END AUTOGENERATED CONFIG FEATURES
+
+#! </details>
\ No newline at end of file
diff --git a/embassy-executor/README.md b/embassy-executor/README.md
index 80ecfc71a..aa9d59907 100644
--- a/embassy-executor/README.md
+++ b/embassy-executor/README.md
@@ -22,7 +22,7 @@ Tasks are allocated from the arena when spawned for the first time. If the task
 The arena size can be configured in two ways:
 
 - Via Cargo features: enable a Cargo feature like `task-arena-size-8192`. Only a selection of values
-  is available, check `Cargo.toml` for the list.
+  is available, see [Task Area Sizes](#task-arena-size) for reference.
 - Via environment variables at build time: set the variable named `EMBASSY_EXECUTOR_TASK_ARENA_SIZE`. For example
   `EMBASSY_EXECUTOR_TASK_ARENA_SIZE=4321 cargo build`. You can also set them in the `[env]` section of `.cargo/config.toml`.
   Any value can be set, unlike with Cargo features.
diff --git a/embassy-executor/gen_config.py b/embassy-executor/gen_config.py
index e427d29f4..cf32bd530 100644
--- a/embassy-executor/gen_config.py
+++ b/embassy-executor/gen_config.py
@@ -45,6 +45,12 @@ things = ""
 for f in features:
     name = f["name"].replace("_", "-")
     for val in f["vals"]:
+        things += f"## {val}"
+        if val == f["default"]:
+            things += " (default)\n"
+        else:
+            things += "\n"
+            
         things += f"{name}-{val} = []"
         if val == f["default"]:
             things += " # Default"
diff --git a/embassy-executor/src/lib.rs b/embassy-executor/src/lib.rs
index 4c6900a6d..eea118ade 100644
--- a/embassy-executor/src/lib.rs
+++ b/embassy-executor/src/lib.rs
@@ -3,6 +3,9 @@
 #![doc = include_str!("../README.md")]
 #![warn(missing_docs)]
 
+//! ## Feature flags
+#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
+
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;