41 files changed, 93 insertions, 31 deletions

diff --git a/docs/README.md b/docs/README.md
index 0bf3a6c89..8b9a3c48d 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 be built like this:
+
+```
+asciidoctor -d book -D thebook/ index.adoc
+```
+
+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/modules/ROOT/examples/basic/Cargo.toml b/docs/examples/basic/Cargo.toml
index 2c282145d..2c282145d 100644
--- a/docs/modules/ROOT/examples/basic/Cargo.toml
+++ b/docs/examples/basic/Cargo.toml
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..943249a17 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/Cargo.toml
+++ b/docs/examples/layer-by-layer/Cargo.toml
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/index.adoc b/docs/index.adoc
new file mode 100644
index 000000000..f0fa6f2b7
--- /dev/null
+++ b/docs/index.adoc
@@ -0,0 +1,15 @@
+:description: Embassy Book
+:sectanchors:
+:doctype: book
+:toc:
+:toc-placement: left
+:toclevels: 2
+
+# 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/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/pages/basic_application.adoc b/docs/pages/basic_application.adoc
index d5aad806d..aa3ea2d1b 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/pages/basic_application.adoc
@@ -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..a7d63f990 100644
--- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
+++ b/docs/pages/embassy_in_the_wild.adoc
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..8b1f22f6e 100644
--- a/docs/modules/ROOT/pages/faq.adoc
+++ b/docs/pages/faq.adoc
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/pages/getting_started.adoc
index 73cb5530d..73cb5530d 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/pages/getting_started.adoc
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