Merge pull request #2958 from embassy-rs/embassy-book-refactor

Embassy book refactor

51 files changed, 154 insertions, 85 deletions

diff --git a/.github/ci/book.sh b/.github/ci/book.sh
new file mode 100644
index 000000000..285cdc8fa
--- /dev/null
+++ b/.github/ci/book.sh
@@ -0,0 +1,17 @@
+#!/bin/bash
+## on push branch=main
+
+set -euxo pipefail
+
+make -C docs
+
+export KUBECONFIG=/ci/secrets/kubeconfig.yml
+POD=$(kubectl -n embassy get po -l app=website -o jsonpath={.items[0].metadata.name})
+
+mkdir -p build
+mv docs/book build/book
+tar -C build -cf book.tar book
+kubectl exec $POD -- mkdir -p /usr/share/nginx/html
+kubectl cp book.tar $POD:/usr/share/nginx/html/
+kubectl exec $POD -- find /usr/share/nginx/html
+kubectl exec $POD -- tar -C /usr/share/nginx/html -xvf /usr/share/nginx/html/book.tar
diff --git a/ci.sh b/ci.sh
index 6fff1e68c..8e37b6178 100755
--- a/ci.sh
+++ b/ci.sh
@@ -171,11 +171,11 @@ cargo batch \
     --- build --release --manifest-path embassy-boot-nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features embassy-nrf/nrf9160-ns \
     --- build --release --manifest-path embassy-boot-rp/Cargo.toml --target thumbv6m-none-eabi \
     --- build --release --manifest-path embassy-boot-stm32/Cargo.toml --target thumbv7em-none-eabi --features embassy-stm32/stm32wl55jc-cm4 \
-    --- build --release --manifest-path docs/modules/ROOT/examples/basic/Cargo.toml --target thumbv7em-none-eabi \
-    --- build --release --manifest-path docs/modules/ROOT/examples/layer-by-layer/blinky-pac/Cargo.toml --target thumbv7em-none-eabi \
-    --- build --release --manifest-path docs/modules/ROOT/examples/layer-by-layer/blinky-hal/Cargo.toml --target thumbv7em-none-eabi \
-    --- build --release --manifest-path docs/modules/ROOT/examples/layer-by-layer/blinky-irq/Cargo.toml --target thumbv7em-none-eabi \
-    --- build --release --manifest-path docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml --target thumbv7em-none-eabi \
+    --- build --release --manifest-path docs/examples/basic/Cargo.toml --target thumbv7em-none-eabi \
+    --- build --release --manifest-path docs/examples/layer-by-layer/blinky-pac/Cargo.toml --target thumbv7em-none-eabi \
+    --- build --release --manifest-path docs/examples/layer-by-layer/blinky-hal/Cargo.toml --target thumbv7em-none-eabi \
+    --- build --release --manifest-path docs/examples/layer-by-layer/blinky-irq/Cargo.toml --target thumbv7em-none-eabi \
+    --- build --release --manifest-path docs/examples/layer-by-layer/blinky-async/Cargo.toml --target thumbv7em-none-eabi \
     --- build --release --manifest-path examples/nrf52840/Cargo.toml --target thumbv7em-none-eabi --out-dir out/examples/nrf52840 \
     --- build --release --manifest-path examples/nrf5340/Cargo.toml --target thumbv8m.main-none-eabihf --out-dir out/examples/nrf5340 \
     --- build --release --manifest-path examples/nrf9160/Cargo.toml --target thumbv8m.main-none-eabihf --out-dir out/examples/nrf9160 \
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 000000000..834802d3b
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,8 @@
+all:
+        asciidoctor -d book -D book/ index.adoc
+        cp -r images book
+
+clean:
+        rm -rf book
+
+.PHONY: all clean
diff --git a/docs/README.md b/docs/README.md
index 0bf3a6c89..94ebd7a05 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,9 @@
 # embassy docs
 
-The documentation hosted at [https://embassy.dev/book](https://embassy.dev/book). Building the documentation requires
-cloning the [embassy-book](https://github.com/embassy-rs/embassy-book) repository and following the instructions.
+The documentation hosted at [https://embassy.dev/book](https://embassy.dev/book). Building the documentation requires the [asciidoctor](https://asciidoctor.org/) tool, and can built running `make` in this folder:
+
+```
+make
+```
+
+Then open the generated file `thebook/index.html`.
diff --git a/docs/antora.yml b/docs/antora.yml
deleted file mode 100644
index 9a00fa820..000000000
--- a/docs/antora.yml
+++ /dev/null
@@ -1,5 +0,0 @@
-name: ROOT
-title: Embassy
-version: dev
-nav:
-  - modules/ROOT/nav.adoc
diff --git a/docs/modules/ROOT/examples/basic/.cargo/config.toml b/docs/examples/basic/.cargo/config.toml
index 8ca28df39..8ca28df39 100644
--- a/docs/modules/ROOT/examples/basic/.cargo/config.toml
+++ b/docs/examples/basic/.cargo/config.toml
diff --git a/docs/examples/basic/Cargo.toml b/docs/examples/basic/Cargo.toml
new file mode 100644
index 000000000..d86d4a809
--- /dev/null
+++ b/docs/examples/basic/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+authors = ["Dario Nieuwenhuis <[email protected]>"]
+edition = "2018"
+name = "embassy-basic-example"
+version = "0.1.0"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+embassy-executor = { version = "0.5.0", path = "../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] }
+embassy-time = { version = "0.3.0", path = "../../../embassy-time", features = ["defmt"] }
+embassy-nrf = { version = "0.1.0", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] }
+
+defmt = "0.3"
+defmt-rtt = "0.3"
+
+cortex-m = { version = "0.7.6", features = ["critical-section-single-core"] }
+cortex-m-rt = "0.7.0"
+panic-probe = { version = "0.3", features = ["print-defmt"] }
diff --git a/docs/modules/ROOT/examples/basic/build.rs b/docs/examples/basic/build.rs
index 30691aa97..30691aa97 100644
--- a/docs/modules/ROOT/examples/basic/build.rs
+++ b/docs/examples/basic/build.rs
diff --git a/docs/modules/ROOT/examples/basic/memory.x b/docs/examples/basic/memory.x
index 9b04edec0..9b04edec0 100644
--- a/docs/modules/ROOT/examples/basic/memory.x
+++ b/docs/examples/basic/memory.x
diff --git a/docs/modules/ROOT/examples/basic/src/main.rs b/docs/examples/basic/src/main.rs
index 4412712c8..4412712c8 100644
--- a/docs/modules/ROOT/examples/basic/src/main.rs
+++ b/docs/examples/basic/src/main.rs
diff --git a/docs/examples/examples b/docs/examples/examples
new file mode 120000
index 000000000..d15735c1d
--- /dev/null
+++ b/docs/examples/examples
@@ -0,0 +1 @@
+../../examples
\ No newline at end of file
diff --git a/docs/modules/ROOT/examples/layer-by-layer/.cargo/config.toml b/docs/examples/layer-by-layer/.cargo/config.toml
index 3012f05dc..3012f05dc 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/.cargo/config.toml
+++ b/docs/examples/layer-by-layer/.cargo/config.toml
diff --git a/docs/modules/ROOT/examples/layer-by-layer/Cargo.toml b/docs/examples/layer-by-layer/Cargo.toml
index 943249a17..0f233eae5 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/Cargo.toml
+++ b/docs/examples/layer-by-layer/Cargo.toml
@@ -8,8 +8,8 @@ members = [
 ]
 
 [patch.crates-io]
-embassy-executor = { path = "../../../../../embassy-executor" }
-embassy-stm32 = { path = "../../../../../embassy-stm32" }
+embassy-executor = { path = "../../../embassy-executor" }
+embassy-stm32 = { path = "../../../embassy-stm32" }
 
 [profile.release]
 codegen-units = 1
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml b/docs/examples/layer-by-layer/blinky-async/Cargo.toml
index 64f7e8403..64f7e8403 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-async/Cargo.toml
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs b/docs/examples/layer-by-layer/blinky-async/src/main.rs
index 004602816..004602816 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
+++ b/docs/examples/layer-by-layer/blinky-async/src/main.rs
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-hal/Cargo.toml b/docs/examples/layer-by-layer/blinky-hal/Cargo.toml
index c15de2db2..c15de2db2 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-hal/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-hal/Cargo.toml
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-hal/src/main.rs b/docs/examples/layer-by-layer/blinky-hal/src/main.rs
index d0c9f4907..d0c9f4907 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-hal/src/main.rs
+++ b/docs/examples/layer-by-layer/blinky-hal/src/main.rs
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/Cargo.toml b/docs/examples/layer-by-layer/blinky-irq/Cargo.toml
index 9733658b6..9733658b6 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-irq/Cargo.toml
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs b/docs/examples/layer-by-layer/blinky-irq/src/main.rs
index 743c9d99b..743c9d99b 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
+++ b/docs/examples/layer-by-layer/blinky-irq/src/main.rs
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-pac/Cargo.toml b/docs/examples/layer-by-layer/blinky-pac/Cargo.toml
index f872b94cb..f872b94cb 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-pac/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-pac/Cargo.toml
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-pac/src/main.rs b/docs/examples/layer-by-layer/blinky-pac/src/main.rs
index 990d46cb6..990d46cb6 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-pac/src/main.rs
+++ b/docs/examples/layer-by-layer/blinky-pac/src/main.rs
diff --git a/docs/modules/ROOT/images/bootloader_flash.png b/docs/images/bootloader_flash.png
index 635783b05..635783b05 100644
--- a/docs/modules/ROOT/images/bootloader_flash.png
+++ b/docs/images/bootloader_flash.png
diff --git a/docs/modules/ROOT/images/embassy_executor.drawio b/docs/images/embassy_executor.drawio
index b76587d97..b76587d97 100644
--- a/docs/modules/ROOT/images/embassy_executor.drawio
+++ b/docs/images/embassy_executor.drawio
diff --git a/docs/modules/ROOT/images/embassy_executor.png b/docs/images/embassy_executor.png
index 2a83a3adb..2a83a3adb 100644
--- a/docs/modules/ROOT/images/embassy_executor.png
+++ b/docs/images/embassy_executor.png
diff --git a/docs/modules/ROOT/images/embassy_irq.drawio b/docs/images/embassy_irq.drawio
index aa439a8e6..aa439a8e6 100644
--- a/docs/modules/ROOT/images/embassy_irq.drawio
+++ b/docs/images/embassy_irq.drawio
diff --git a/docs/modules/ROOT/images/embassy_irq.png b/docs/images/embassy_irq.png
index 154d336b6..154d336b6 100644
--- a/docs/modules/ROOT/images/embassy_irq.png
+++ b/docs/images/embassy_irq.png
diff --git a/docs/index.adoc b/docs/index.adoc
new file mode 100644
index 000000000..9c6150196
--- /dev/null
+++ b/docs/index.adoc
@@ -0,0 +1,16 @@
+:description: Embassy Book
+:sectanchors:
+:doctype: book
+:toc:
+:toc-placement: left
+:toclevels: 2
+:imagesdir: images
+
+# Embassy Book
+
+Welcome to the Embassy Book. The Embassy Book is for everyone who wants to use Embassy and understand how Embassy works.
+
+include::pages/overview.adoc[leveloffset = 1]
+include::pages/beginners.adoc[leveloffset = 1]
+include::pages/system.adoc[leveloffset = 1]
+include::pages/faq.adoc[leveloffset = 1]
diff --git a/docs/modules/ROOT/examples/basic/Cargo.toml b/docs/modules/ROOT/examples/basic/Cargo.toml
deleted file mode 100644
index 2c282145d..000000000
--- a/docs/modules/ROOT/examples/basic/Cargo.toml
+++ /dev/null
@@ -1,18 +0,0 @@
-[package]
-authors = ["Dario Nieuwenhuis <[email protected]>"]
-edition = "2018"
-name = "embassy-basic-example"
-version = "0.1.0"
-license = "MIT OR Apache-2.0"
-
-[dependencies]
-embassy-executor = { version = "0.5.0", path = "../../../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] }
-embassy-time = { version = "0.3.0", path = "../../../../../embassy-time", features = ["defmt"] }
-embassy-nrf = { version = "0.1.0", path = "../../../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] }
-
-defmt = "0.3"
-defmt-rtt = "0.3"
-
-cortex-m = { version = "0.7.6", features = ["critical-section-single-core"] }
-cortex-m-rt = "0.7.0"
-panic-probe = { version = "0.3", features = ["print-defmt"] }
diff --git a/docs/modules/ROOT/examples/examples b/docs/modules/ROOT/examples/examples
deleted file mode 120000
index 1929330b0..000000000
--- a/docs/modules/ROOT/examples/examples
+++ /dev/null
@@ -1 +0,0 @@
-../../../../examples
\ No newline at end of file
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
deleted file mode 100644
index 44b0eddb9..000000000
--- a/docs/modules/ROOT/nav.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-* xref:getting_started.adoc[Getting started]
-** xref:basic_application.adoc[Basic application]
-** xref:project_structure.adoc[Project Structure]
-** xref:new_project.adoc[Starting a new Embassy project]
-** xref:best_practices.adoc[Best Practices]
-* xref:runtime.adoc[Executor]
-* xref::time_keeping.adoc[Time-keeping]
-* xref:sharing_peripherals.adoc[Sharing peripherals]
-* xref:hal.adoc[HAL]
-** xref:layer_by_layer.adoc[Anatomy of an async HAL]
-** xref:nrf.adoc[nRF]
-** xref:stm32.adoc[STM32]
-* xref:bootloader.adoc[Bootloader]
-
-* xref:examples.adoc[Examples]
-* xref:developer.adoc[Developer Docs]
-** xref:developer_stm32.adoc[Developer Docs: STM32]
-* xref:embassy_in_the_wild.adoc[Embassy in the wild]
-* xref:faq.adoc[Frequently Asked Questions]
diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/pages/basic_application.adoc
index d5aad806d..7b4ebda4f 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/pages/basic_application.adoc
@@ -1,10 +1,10 @@
 = A basic Embassy application
 
-So you've got one of the xref:examples.adoc[examples] running, but what now? Let's go through a simple Embassy application for the nRF52 DK to understand it better.
+So you've got one of the examples running, but what now? Let's go through a simple Embassy application for the nRF52 DK to understand it better.
 
 == Main
 
-The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/modules/ROOT/examples/basic[here].
+The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/examples/basic[here].
 
 NOTE: If you’re using VS Code and rust-analyzer to view and edit the examples, you may need to make some changes to `.vscode/settings.json` to tell it which project we’re working on. Follow the instructions commented in that file to get rust-analyzer working correctly.
 
@@ -14,7 +14,7 @@ The first thing you’ll notice are two attributes at the top of the file. These
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="1..2"]
+include::../examples/basic/src/main.rs[lines="1..2"]
 ----
 
 === Dealing with errors
@@ -23,7 +23,7 @@ Then, what follows are some declarations on how to deal with panics and faults.
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="8"]
+include::../examples/basic/src/main.rs[lines="8"]
 ----
 
 === Task declaration
@@ -32,7 +32,7 @@ After a bit of import declaration, the tasks run by the application should be de
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="10..18"]
+include::../examples/basic/src/main.rs[lines="10..18"]
 ----
 
 An embassy task must be declared `async`, and may NOT take generic arguments. In this case, we are handed the LED that should be blinked and the interval of the blinking.
@@ -47,7 +47,7 @@ We then initialize the HAL with a default config, which gives us a `Peripherals`
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="20..-1"]
+include::../examples/basic/src/main.rs[lines="20..-1"]
 ----
 
 What happens when the `blinker` task has been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy_executor::main]` macro. The macro does the following:
@@ -64,7 +64,7 @@ The project definition needs to contain the embassy dependencies:
 
 [source,toml]
 ----
-include::example$basic/Cargo.toml[lines="9..11"]
+include::../examples/basic/Cargo.toml[lines="9..11"]
 ----
 
 Depending on your microcontroller, you may need to replace `embassy-nrf` with something else (`embassy-stm32` for STM32. Remember to update feature flags as well).
diff --git a/docs/pages/beginners.adoc b/docs/pages/beginners.adoc
new file mode 100644
index 000000000..48c9f4541
--- /dev/null
+++ b/docs/pages/beginners.adoc
@@ -0,0 +1,11 @@
+= For beginners
+
+The articles in this section are primarily aimed at users new to Embassy,
+showing how to get started, how to structure your project and other best practices.
+
+include::getting_started.adoc[leveloffset = 2]
+include::basic_application.adoc[leveloffset = 2]
+include::project_structure.adoc[leveloffset = 2]
+include::new_project.adoc[leveloffset = 2]
+include::best_practices.adoc[leveloffset = 2]
+include::layer_by_layer.adoc[leveloffset = 2]
diff --git a/docs/modules/ROOT/pages/best_practices.adoc b/docs/pages/best_practices.adoc
index bfcedec06..bfcedec06 100644
--- a/docs/modules/ROOT/pages/best_practices.adoc
+++ b/docs/pages/best_practices.adoc
diff --git a/docs/modules/ROOT/pages/bootloader.adoc b/docs/pages/bootloader.adoc
index 3b0cdb182..3b0cdb182 100644
--- a/docs/modules/ROOT/pages/bootloader.adoc
+++ b/docs/pages/bootloader.adoc
diff --git a/docs/modules/ROOT/pages/developer.adoc b/docs/pages/developer.adoc
index e03ee51a8..e03ee51a8 100644
--- a/docs/modules/ROOT/pages/developer.adoc
+++ b/docs/pages/developer.adoc
diff --git a/docs/modules/ROOT/pages/developer_stm32.adoc b/docs/pages/developer_stm32.adoc
index 7c04ab1a4..7c04ab1a4 100644
--- a/docs/modules/ROOT/pages/developer_stm32.adoc
+++ b/docs/pages/developer_stm32.adoc
diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/pages/embassy_in_the_wild.adoc
index a7d63f990..76b1169bd 100644
--- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
+++ b/docs/pages/embassy_in_the_wild.adoc
@@ -1,6 +1,6 @@
 = Embassy in the wild!
 
-Here are known examples of real-world projects which make use of Embassy. Feel free to link:https://github.com/embassy-rs/embassy/blob/main/docs/modules/ROOT/pages/embassy_in_the_wild.adoc[add more]!
+Here are known examples of real-world projects which make use of Embassy. Feel free to link:https://github.com/embassy-rs/embassy/blob/main/docs/pages/embassy_in_the_wild.adoc[add more]!
 
 * link:https://github.com/haobogu/rmk/[RMK: A feature-rich Rust keyboard firmware]
 ** RMK has built-in layer support, wireless(BLE) support, real-time key editing support using vial, and more! 
@@ -10,8 +10,8 @@ Here are known examples of real-world projects which make use of Embassy. Feel f
 * link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device
 ** Targets the ESP32-S3 or ESP32-C6 MCU
 * The link:https://github.com/lora-rs/lora-rs[lora-rs] project includes link:https://github.com/lora-rs/lora-rs/tree/main/examples/stm32l0/src/bin[various standalone examples] for NRF52840, RP2040, STM32L0 and STM32WL
-** link:https://github.com/matoushybl/air-force-one[Air force one: A simple air quality monitoring system]
-*** Targets nRF52 and uses nrf-softdevice
+* link:https://github.com/matoushybl/air-force-one[Air force one: A simple air quality monitoring system]
+** Targets nRF52 and uses nrf-softdevice
 
 * link:https://github.com/schmettow/ylab-edge-go[YLab Edge Go] and link:https://github.com/schmettow/ylab-edge-pro[YLab Edge Pro] projects develop 
 firmware (RP2040, STM32) for capturing physiological data in behavioural science research. Included so far are:
diff --git a/docs/modules/ROOT/pages/examples.adoc b/docs/pages/examples.adoc
index c852f5205..82381a2c5 100644
--- a/docs/modules/ROOT/pages/examples.adoc
+++ b/docs/pages/examples.adoc
@@ -7,5 +7,5 @@ Main loop example
 
 [source,rust]
 ----
-include::example$examples/std/src/bin/tick.rs[]
+include::../examples/examples/std/src/bin/tick.rs[]
 ----
diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/pages/faq.adoc
index 8b1f22f6e..5f50951d8 100644
--- a/docs/modules/ROOT/pages/faq.adoc
+++ b/docs/pages/faq.adoc
@@ -2,7 +2,7 @@
 
 These are a list of unsorted, commonly asked questions and answers.
 
-Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit/main/docs/modules/ROOT/pages/faq.adoc[this page], especially if someone in the chat answered a question for you!
+Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit/main/docs/pages/faq.adoc[this page], especially if someone in the chat answered a question for you!
 
 == How to deploy to RP2040 without a debugging probe.
 
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/pages/getting_started.adoc
index 73cb5530d..465059922 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/pages/getting_started.adoc
@@ -137,7 +137,7 @@ If you’re still having problems, check the link:https://embassy.dev/book/dev/f
 
 Congratulations, you have your first Embassy application running! Here are some suggestions for where to go from here:
 
-* Read more about the xref:runtime.adoc[executor].
-* Read more about the xref:hal.adoc[HAL].
-* Start xref:basic_application.adoc[writing your application].
-* Learn how to xref:new_project.adoc[start a new embassy project by adapting an example].
+* Read more about the xref:_embassy_executor[executor].
+* Read more about the xref:_hardware_abstraction_layer_hal[HAL].
+* Start xref:_a_basic_embassy_application[writing your application].
+* Learn how to xref:_starting_a_new_project[start a new embassy project by adapting an example].
diff --git a/docs/modules/ROOT/pages/hal.adoc b/docs/pages/hal.adoc
index 14b85e1f1..14b85e1f1 100644
--- a/docs/modules/ROOT/pages/hal.adoc
+++ b/docs/pages/hal.adoc
diff --git a/docs/modules/ROOT/pages/layer_by_layer.adoc b/docs/pages/layer_by_layer.adoc
index fa419f75e..f87291c20 100644
--- a/docs/modules/ROOT/pages/layer_by_layer.adoc
+++ b/docs/pages/layer_by_layer.adoc
@@ -16,7 +16,7 @@ The blinky app using PAC is shown below:
 
 [source,rust]
 ----
-include::example$layer-by-layer/blinky-pac/src/main.rs[]
+include::../examples/layer-by-layer/blinky-pac/src/main.rs[]
 ----
 
 As you can see, a lot of code is needed to enable the peripheral clocks and to configure the input pins and the output pins of the application.
@@ -35,7 +35,7 @@ The HAL example is shown below:
 
 [source,rust]
 ----
-include::example$layer-by-layer/blinky-hal/src/main.rs[]
+include::../examples/layer-by-layer/blinky-hal/src/main.rs[]
 ----
 
 As you can see, the application becomes a lot simpler, even without using any async code. The `Input` and `Output` types hide all the details of accessing the GPIO registers and allow you to use a much simpler API for querying the state of the button and toggling the LED output.
@@ -52,7 +52,7 @@ Given Embassy focus on async Rust (which we'll come back to after this example),
 
 [source,rust]
 ----
-include::example$layer-by-layer/blinky-irq/src/main.rs[lines="1..57"]
+include::../examples/layer-by-layer/blinky-irq/src/main.rs[lines="1..57"]
 ----
 
 The simple application is now more complex again, primarily because of the need to keep the button and LED states in the global scope where it is accessible by the main application loop, as well as the interrupt handler.
@@ -67,7 +67,7 @@ It's time to use the Embassy capabilities to its fullest. At the core, Embassy h
 
 [source,rust]
 ----
-include::example$layer-by-layer/blinky-async/src/main.rs[]
+include::../examples/layer-by-layer/blinky-async/src/main.rs[]
 ----
 
 The async version looks very similar to the HAL version, apart from a few minor details:
diff --git a/docs/modules/ROOT/pages/new_project.adoc b/docs/pages/new_project.adoc
index 320966bb6..346d9f0f8 100644
--- a/docs/modules/ROOT/pages/new_project.adoc
+++ b/docs/pages/new_project.adoc
@@ -1,17 +1,18 @@
-= Starting a new Embassy project
+= Starting a new project
 
 Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project.
 
-There are some tools for generating Embassy projects: (WIP)
+== Tools for generating Embassy projects
 
-==== CLI
+=== CLI
 - link:https://github.com/adinack/cargo-embassy[cargo-embassy] (STM32 and NRF)
 
-==== cargo-generate
+=== cargo-generate
 - link:https://github.com/lulf/embassy-template[embassy-template] (STM32, NRF, and RP)
 - link:https://github.com/bentwire/embassy-rp2040-template[embassy-rp2040-template] (RP)
 
-But if you want to start from scratch:
+
+== Starting a project from scratch
 
 As an example, let’s create a new embassy project from scratch for a STM32G474. The same instructions are applicable for any supported chip with some minor changes.
 
@@ -35,7 +36,7 @@ stm32g474-example
 
 Looking in link:https://github.com/embassy-rs/embassy/tree/main/examples[the Embassy examples], we can see there’s a `stm32g4` folder. Find `src/blinky.rs` and copy its contents into our `src/main.rs`.
 
-== .cargo/config.toml
+=== The .cargo/config.toml
 
 Currently, we’d need to provide cargo with a target triple every time we run `cargo build` or `cargo run`. Let’s spare ourselves that work by copying `.cargo/config.toml` from `examples/stm32g4` into our project.
 
@@ -66,7 +67,7 @@ and copying `STM32G474RETx` into `.cargo/config.toml` as so:
 runner = "probe-rs run --chip STM32G474RETx"
 ----
 
-== Cargo.toml
+=== Cargo.toml
 
 Now that cargo knows what target to compile for (and probe-rs knows what chip to run it on), we’re ready to add some dependencies.
 
@@ -117,7 +118,7 @@ Finally, copy the `[profile.release]` section from the example `Cargo.toml` into
 debug = 2
 ----
 
-== rust-toolchain.toml
+=== rust-toolchain.toml
 
 Before we can build our project, we need to add an additional file to tell cargo to use the nightly toolchain. Copy the `rust-toolchain.toml` from the embassy repo to ours, and trim the list of targets down to only the target triple relevent for our project — in this case, `thumbv7em-none-eabi`:
 
@@ -142,7 +143,7 @@ components = [ "rust-src", "rustfmt", "llvm-tools", "miri" ]
 targets = ["thumbv7em-none-eabi"]
 ----
 
-== build.rs
+=== build.rs
 
 In order to produce a working binary for our target, cargo requires a custom build script. Copy `build.rs` from the example to our project:
 
@@ -158,7 +159,7 @@ stm32g474-example
     └── main.rs
 ----
 
-== Building and running
+=== Building and running
 
 At this point, we‘re finally ready to build and run our project! Connect your board via a debug probe and run:
 
diff --git a/docs/modules/ROOT/pages/nrf.adoc b/docs/pages/nrf.adoc
index 1706087ae..1706087ae 100644
--- a/docs/modules/ROOT/pages/nrf.adoc
+++ b/docs/pages/nrf.adoc
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/pages/overview.adoc
index 7116f357f..1b9381bfe 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/pages/overview.adoc
@@ -1,4 +1,4 @@
-= Embassy
+= Introduction
 
 Embassy is a project to make async/await a first-class option for embedded development.
 
@@ -56,6 +56,20 @@ For most I/O in embedded devices, the peripheral doesn't directly support the tr
 
 The Direct Memory Access controller (DMA) is a controller that is present in MCUs that Embassy supports, including stm32 and nrf. The DMA allows the MCU to set up a transfer, either send or receive, and then wait for the transfer to complete. With DMA, once started, no MCU intervention is required until the transfer is complete, meaning that the MCU can perform other computation, or set up other I/O while the transfer is in progress. For high I/O rates, DMA can cut the time that the MCU spends handling I/O by over half. However, because DMA is more complex to set-up, it is less widely used in the embedded community. Embassy aims to change that by making DMA the first choice rather than the last. Using Embassy, there's no additional tuning required once I/O rates increase because your application is already set-up to handle them.
 
+== Examples
+
+Embassy provides examples for all HALs supported. You can find them in the `examples/` folder.
+
+
+Main loop example
+
+[source,rust]
+----
+include::../examples/examples/std/src/bin/tick.rs[]
+----
+
+include::embassy_in_the_wild.adoc[leveloffset = 2]
+
 == Resources
 
 For more reading material on async Rust and Embassy:
diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/pages/project_structure.adoc
index 2adfcc1df..722ec8d9d 100644
--- a/docs/modules/ROOT/pages/project_structure.adoc
+++ b/docs/pages/project_structure.adoc
@@ -18,6 +18,7 @@ my-project
 |- rust-toolchain.toml
 ----
 
+[discrete]
 == .cargo/config.toml
 
 This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device.
@@ -36,21 +37,27 @@ target = "thumbv6m-none-eabi" # <-change for your platform
 DEFMT_LOG = "trace" # <- can change to info, warn, or error
 ----
 
+[discrete]
 == build.rs
 
 This is the build script for your project. It links defmt (what is link:https://defmt.ferrous-systems.com[defmt]?) and the `memory.x` file if needed. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example].
 
+[discrete]
 == Cargo.toml
 
 This is your manifest file, where you can configure all of the embassy components to use the features you need.
 
-==== Features
-===== Time
+[discrete]
+=== Features
+
+[discrete]
+==== Time
 - tick-hz-x: Configures the tick rate of `embassy-time`. Higher tick rate means higher precision, and higher CPU wakes.
 - defmt-timestamp-uptime: defmt log entries will display the uptime in seconds.
 
 ...more to come
 
+[discrete]
 == memory.x
 
 This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x.
@@ -68,6 +75,7 @@ MEMORY
 }
 ----
 
+[discrete]
 == rust-toolchain.toml
 
 This file configures the rust version and configuration to use.
diff --git a/docs/modules/ROOT/pages/runtime.adoc b/docs/pages/runtime.adoc
index f2812dd7c..f2812dd7c 100644
--- a/docs/modules/ROOT/pages/runtime.adoc
+++ b/docs/pages/runtime.adoc
diff --git a/docs/modules/ROOT/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc
index 6bcd56b01..6bcd56b01 100644
--- a/docs/modules/ROOT/pages/sharing_peripherals.adoc
+++ b/docs/pages/sharing_peripherals.adoc
diff --git a/docs/modules/ROOT/pages/stm32.adoc b/docs/pages/stm32.adoc
index 7bfc0592b..7bfc0592b 100644
--- a/docs/modules/ROOT/pages/stm32.adoc
+++ b/docs/pages/stm32.adoc
diff --git a/docs/pages/system.adoc b/docs/pages/system.adoc
new file mode 100644
index 000000000..985f92b18
--- /dev/null
+++ b/docs/pages/system.adoc
@@ -0,0 +1,13 @@
+= System description
+
+This section describes different parts of Embassy in more detail.
+
+include::runtime.adoc[leveloffset = 2]
+include::bootloader.adoc[leveloffset = 2]
+include::time_keeping.adoc[leveloffset = 2]
+include::hal.adoc[leveloffset = 2]
+include::nrf.adoc[leveloffset = 2]
+include::stm32.adoc[leveloffset = 2]
+include::sharing_peripherals.adoc[leveloffset = 2]
+include::developer.adoc[leveloffset = 2]
+include::developer_stm32.adoc[leveloffset = 2]
diff --git a/docs/modules/ROOT/pages/time_keeping.adoc b/docs/pages/time_keeping.adoc
index 17492a884..17492a884 100644
--- a/docs/modules/ROOT/pages/time_keeping.adoc
+++ b/docs/pages/time_keeping.adoc