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

Embassy book refactor

.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

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 \

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

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

docs/antora.yml

@@ -1,5 +0,0 @@
-name: ROOT
-title: Embassy
-version: dev
-nav:
-  - modules/ROOT/nav.adoc

docs/examples/basic/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+authors = ["Dario Nieuwenhuis <dirbaio@dirbaio.net>"]
+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"] }

docs/examples/examples

@@ -0,0 +1 @@
+../../examples

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

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]

docs/modules/ROOT/examples/basic/Cargo.toml

@@ -1,18 +0,0 @@
-[package]
-authors = ["Dario Nieuwenhuis <dirbaio@dirbaio.net>"]
-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"] }

docs/modules/ROOT/examples/examples

@@ -1 +0,0 @@
-../../../../examples

docs/modules/ROOT/nav.adoc

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

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

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]

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:

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

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.
 

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

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:

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:
 

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:

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.

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]