docs: add keymap configuration chapter to doc

Signed-off-by: HaoboGu <[email protected]>

docs/src/SUMMARY.md

@@ -12,7 +12,7 @@
 - [Compile and flash!](compile_and_flash.md)
 
 # Features
-- [Keymap configuration]()
+- [Keymap configuration](keymap_configuration.md)
 - [Layers]()
 - [Vial support]()
 - [Tap hold]()

docs/src/guide_overview.md

@@ -1,15 +1,15 @@
 # Overview
 
-This guide introduces how to build your own keyboard firmware using RMK. There are 3 sections of the guide:
+This guide aims to introduce you how to build your own keyboard firmware using RMK and run it on your microcontroller. There are 3 steps of the guide:
 
 - setup the RMK environment
 
 - create a RMK project
 
 - compile the firmware and flash
 
-After completing the all 3 section of the guide, you'll learn how to create your personal keyboard firmware using RMK and make it run on your real-world hardware!
+If you get any questions or problems following this guide, please fire an issue at https://github.com/HaoboGu/rmk/issues.
 
 ## Before we start
 
-Using RMK requires basic knowledge of **Rust programming and embedded devices**. If you're not familiar with Rust, [The Official Rust Book](https://doc.rust-lang.org/book/) is a good start. And if you're not familiar with embedded Rust, we recommend you to read [The Embedded Rust Book](https://docs.rust-embedded.org/book/) first. We'll keep working on making RMK more accessible for everybody.
+Using RMK requires basic knowledge of **Rust programming and embedded devices**. If you're not familiar with Rust, [The Official Rust Book](https://doc.rust-lang.org/book/) is a good start. And, if you're not familiar with embedded Rust, we recommend you to read [The Embedded Rust Book](https://docs.rust-embedded.org/book/) first. We'll keep working on making RMK more accessible for everybody.

docs/src/keymap_configuration.md

@@ -0,0 +1,51 @@
+# Keymap configuration
+
+RMK supports configuring the default keymap at the compile time. Keymap in RMK is a 3-D matrix of [`KeyAction`](https://docs.rs/rmk/latest/rmk/action/enum.KeyAction.html), which represent the keyboard's action after you trigger a physical key. The 3 dimensions are the number of columns, rows and layers.
+
+The default keymap should be defined at a Rust source file, [rmk-template](https://github.com/HaoboGu/rmk-template) provides an initial [`keymap.rs`](https://github.com/HaoboGu/rmk-template/blob/master/src/keymap.rs) which could be a good example of definiting keymaps in RMK:
+
+```rust
+/// https://github.com/HaoboGu/rmk-template/blob/master/src/keymap.rs
+use rmk::action::KeyAction;
+use rmk::{a, k, layer, mo};
+pub(crate) const COL: usize = 3;
+pub(crate) const ROW: usize = 4;
+pub(crate) const NUM_LAYER: usize = 2;
+
+#[rustfmt::skip]
+pub static KEYMAP: [[[KeyAction; COL]; ROW]; NUM_LAYER] = [
+    layer!([
+        [k!(AudioVolUp), k!(B), k!(AudioVolDown)],
+        [k!(Kp4), k!(LShift), k!(Kp6)],
+        [mo!(1), k!(Kp2), k!(Kp3)],
+        [mo!(1), a!(No), k!(Kp0)]
+    ]),
+    layer!([
+        [k!(Kp7), k!(Kp8), k!(Kp9)],
+        [k!(Kp4), k!(LCtrl), k!(Kp6)],
+        [mo!(1), k!(Kp2), k!(Kp3)],
+        [mo!(1), a!(No), k!(Kp0)]
+    ]),
+];
+```
+
+First of all, the keyboard matrix's basic info is defined as consts:
+
+```rust
+pub(crate) const COL: usize = 3;
+pub(crate) const ROW: usize = 4;
+pub(crate) const NUM_LAYER: usize = 2;
+```
+
+Then, the keymap is defined as a static 3-D matrix of `KeyAction`: 
+
+```rust
+pub static KEYMAP: [[[KeyAction; COL]; ROW]; NUM_LAYER] = [
+    ...
+]
+```
+
+`KEYMAP` is defined as a slice of layers and a layer is defined as a slice of rows and a row is defined as a slice of cols. So the order of keymap matrix is fixed. 
+
+RMK provides a bunch of macros which simplify the keymap definition a lot. You can check all the macros [here](https://docs.rs/rmk/latest/rmk/index.html#macros). For example, `layer!` macro is used to define a layer. Each layer contains several row slices. And in each row slice, the `KeyAction` is defined. To define a normal key in the keymap, `k!` macro is used. If there is no actual key at a position, you can use `a!(No)` to represent `KeyAction::No`.
+

docs/src/roadmap.md

@@ -2,16 +2,21 @@
 
 There are a bunch of things to do with RMK in the near future. The following is a simple TODO list:
 
-- [x] basic functionalities: HID keyboard, layer support, vial support, eeprom support
+- [x] layer support
+- [x] system/media keys
+- [x] mouse keys
+- [x] vial support
+- [x] eeprom
 - [x] project template
-- [ ] better documentation
+- [x] LED
+- [x] (experimental) wireless - BLE
+- [ ] (BLE) auto switch between BLE/USB, on-the-fly mutliple device support, battery service from ADC  
 - [ ] keyboard macro
+- [ ] better documentation
 - [ ] RGB
 - [ ] encoder
-- [ ] 🚧 wireless
-- [ ] split keyboard support
 - [ ] default bootloader/DFU
 - [ ] a good gui configurator
 - [ ] ~~easy keyboard configuration with good default~~(haven't found a good way to achieve this, if you got any idea, ping me pls)
 
-If anyone wants to contribute, please feel free to open an issue or PR, or just ping me! Any forms of contribution are welcome!
+If you want to contribute, please feel free to open an issue or PR, or just ping me! Any forms of contribution are welcome!