feat(docs): Improve the toolchain setup page (#2272)

Split the toolchain setup into separate docker and native pages and improve instructions to better refer to Zephyr docs in certain steps. Also refactor to improve consistency and add virtualenv instructions. --------- Co-authored-by: KemoNine <[email protected]> Co-authored-by: Cem Aksoylar <[email protected]>
zmkfirmware · Jun 2, 2024 · 308d6bc · 308d6bc
1 parent 2d96f46
commit 308d6bc
Show file tree

Hide file tree

Showing 17 changed files with 456 additions and 338 deletions.
diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md
@@ -19,7 +19,7 @@ There's been lots of various activity in ZMK land!
 - Tons of [documentation](/docs) work.
 - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/features/keymaps) to make them simpler for users.
 - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.
-- An initial [`setup.sh`](http://localhost:3000/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
+- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
 - Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added.
 - Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added.
 

diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md
@@ -61,7 +61,7 @@ Once the container has rebuilt, VS Code will be running the 2.5 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 2.5:
 
-- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - run `west update` to pull the updated Zephyr version and its dependencies
 

diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md
@@ -62,7 +62,7 @@ Once the container has rebuilt, VS Code will be running the 3.0 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 3.0:
 
-- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - run `west update` to pull the updated Zephyr version and its dependencies
 

diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md
@@ -132,7 +132,7 @@ Another persistent bug that Apple users experienced was related to crashes and p
 The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes:
 
 - [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
-- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
+- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader-reset) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
 
 #### Split Connections
 

diff --git a/docs/blog/2023-04-06-zephyr-3-2.md b/docs/blog/2023-04-06-zephyr-3-2.md
@@ -87,7 +87,7 @@ Once the container has rebuilt, VS Code will be running the 3.2 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 3.2:
 
-- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - Install the latest version of `west` by running `pip3 install --user --update west`.
 - pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - run `west update` to pull the updated Zephyr version and its dependencies

diff --git a/docs/blog/2024-02-09-zephyr-3-5.md b/docs/blog/2024-02-09-zephyr-3-5.md
@@ -70,7 +70,7 @@ Once the container has rebuilt, VS Code will be running the 3.5 Docker image.
 
 The following steps will get you building ZMK locally against Zephyr 3.5:
 
-- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
 - Install the latest version of `west` by running `pip3 install --user --update west`.
 - Pull the latest ZMK `main` with `git pull` for your ZMK checkout
 - Run `west update` to pull the updated Zephyr version and its dependencies

diff --git a/docs/docs/behaviors/index.mdx b/docs/docs/behaviors/index.mdx
@@ -46,10 +46,10 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
 
 ## Reset behaviors
 
-| Binding       | Behavior                          | Description                                                                              |
-| ------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
-| `&sys_reset`  | [Reset](reset.md#reset)           | Resets the keyboard and re-runs the firmware flashed to the device                       |
-| `&bootloader` | [Bootloader](reset.md#bootloader) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
+| Binding       | Behavior                                | Description                                                                              |
+| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `&sys_reset`  | [Reset](reset.md#reset)                 | Resets the keyboard and re-runs the firmware flashed to the device                       |
+| `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
 
 ## Output selection behaviors
 

diff --git a/docs/docs/customization.md b/docs/docs/customization.md
@@ -40,7 +40,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
 :::
 
 :::note
-It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.mdx) and
+It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup/index.md) and
 [building instructions](development/build-flash.mdx), which includes pointers to
 [building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder).
 :::

diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/new-shield.mdx
@@ -554,7 +554,7 @@ Add additional bindings as necessary to match the default number of encoders on
 
 ### GitHub Actions
 
-Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.mdx),
+Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup/index.md),
 at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
 
 - Add all your pending changes with `git add .`
@@ -566,7 +566,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste
 ### Local Build
 
 :::note
-To build locally, be sure you've followed the [development setup](./setup.mdx) guide first.
+To build locally, be sure you've followed the [development setup](./setup/index.md) guide first.
 :::
 
 Once you've fully created the new keyboard shield definition,