From 4d42e792c5fe71156ca5618513645a0e825e2fc2 Mon Sep 17 00:00:00 2001 From: innovaker <66737976+innovaker@users.noreply.github.com> Date: Wed, 11 Nov 2020 14:12:14 +0000 Subject: refactor(docs): Remove explicit document ids Aligns older documents with newer file-based ids. --- docs/docs/customization.md | 1 - docs/docs/dev-boards-shields-keymaps.md | 1 - docs/docs/dev-build-flash.md | 111 +++++++++++++++++++++++++++++++ docs/docs/dev-build.md | 112 -------------------------------- docs/docs/dev-clean-room.md | 1 - docs/docs/dev-guide-usb-logging.md | 1 - docs/docs/dev-posix-board.md | 1 - docs/docs/dev-setup.md | 3 +- docs/docs/dev-tests.md | 1 - docs/docs/faq.md | 1 - docs/docs/feature/keymaps.md | 1 - docs/docs/hardware.md | 1 - docs/docs/intro.md | 1 - docs/docs/troubleshooting.md | 1 - docs/docs/user-setup.md | 1 - 15 files changed, 112 insertions(+), 126 deletions(-) create mode 100644 docs/docs/dev-build-flash.md delete mode 100644 docs/docs/dev-build.md (limited to 'docs') diff --git a/docs/docs/customization.md b/docs/docs/customization.md index b42656d..d3372da 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -1,5 +1,4 @@ --- -id: customization title: Customizing ZMK/`zmk-config` folders sidebar_label: Customizing ZMK --- diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index 9ed5a32..119db42 100644 --- a/docs/docs/dev-boards-shields-keymaps.md +++ b/docs/docs/dev-boards-shields-keymaps.md @@ -1,5 +1,4 @@ --- -id: dev-boards-shields-keymaps title: Boards, Shields, and Keymaps --- diff --git a/docs/docs/dev-build-flash.md b/docs/docs/dev-build-flash.md new file mode 100644 index 0000000..bfdd464 --- /dev/null +++ b/docs/docs/dev-build-flash.md @@ -0,0 +1,111 @@ +--- +title: Building and Flashing +sidebar_label: Building and Flashing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +## Building + +From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: + +```sh +cd app +``` + +To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +an onboard MCU, or one that uses an MCU board addon. + +### Keyboard (Shield) + MCU Board + +ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) + +Given the following: + +- MCU Board: Proton-C +- Keyboard PCB: kyria_left +- Keymap: default + +You can build ZMK with the following: + +```sh +west build -b proton_c -- -DSHIELD=kyria_left +``` + +### Keyboard With Onboard MCU + +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. + +Given the following: + +- Keyboard: Planck (rev6) +- Keymap: default + +you can build ZMK with the following: + +```sh +west build -b planck_rev6 +``` + +### Pristine Building + +When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: + +```sh +west build -p -b proton_c -- -DSHIELD=kyria_left +``` + +### Building For Split Keyboards + +:::note +For split keyboards, you will have to build and flash each side separately the first time you install ZMK. +::: + +By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: + +``` +west build -d build/left -b nice_nano -- -DSHIELD=kyria_left +``` + +and then building right into `build/right`: + +``` +west build -d build/right -b nice_nano -- -DSHIELD=kyria_right +``` + +This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. + +### Building from `zmk-config` Folder + +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding +`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** + +For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: + +``` +west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" +``` + +## Flashing + +Once built, the previously supplied parameters will be remembered so you can run the following to flash your +board with it in bootloader mode: + +``` +west flash +``` + +For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md deleted file mode 100644 index 3e6b19a..0000000 --- a/docs/docs/dev-build.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -id: dev-build-flash -title: Building and Flashing -sidebar_label: Building and Flashing ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const OsTabs = (props) => ({props.children}); - -## Building - -From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: - -```sh -cd app -``` - -To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with -an onboard MCU, or one that uses an MCU board addon. - -### Keyboard (Shield) + MCU Board - -ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) - -Given the following: - -- MCU Board: Proton-C -- Keyboard PCB: kyria_left -- Keymap: default - -You can build ZMK with the following: - -```sh -west build -b proton_c -- -DSHIELD=kyria_left -``` - -### Keyboard With Onboard MCU - -Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. - -Given the following: - -- Keyboard: Planck (rev6) -- Keymap: default - -you can build ZMK with the following: - -```sh -west build -b planck_rev6 -``` - -### Pristine Building - -When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: - -```sh -west build -p -b proton_c -- -DSHIELD=kyria_left -``` - -### Building For Split Keyboards - -:::note -For split keyboards, you will have to build and flash each side separately the first time you install ZMK. -::: - -By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: - -``` -west build -d build/left -b nice_nano -- -DSHIELD=kyria_left -``` - -and then building right into `build/right`: - -``` -west build -d build/right -b nice_nano -- -DSHIELD=kyria_right -``` - -This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. - -### Building from `zmk-config` Folder - -Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding -`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** - -For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: - -``` -west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" -``` - -## Flashing - -Once built, the previously supplied parameters will be remembered so you can run the following to flash your -board with it in bootloader mode: - -``` -west flash -``` - -For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. diff --git a/docs/docs/dev-clean-room.md b/docs/docs/dev-clean-room.md index 2f301ec..82db3a0 100644 --- a/docs/docs/dev-clean-room.md +++ b/docs/docs/dev-clean-room.md @@ -1,5 +1,4 @@ --- -id: dev-clean-room title: Clean Room Implementation sidebar_label: Clean Room --- diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 50884be..3dc62e3 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -1,5 +1,4 @@ --- -id: dev-guide-usb-logging title: USB Logging --- diff --git a/docs/docs/dev-posix-board.md b/docs/docs/dev-posix-board.md index e146bf1..71460a8 100644 --- a/docs/docs/dev-posix-board.md +++ b/docs/docs/dev-posix-board.md @@ -1,5 +1,4 @@ --- -id: dev-posix-board title: Native Posix board target --- diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 604f987..864574a 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -1,5 +1,4 @@ --- -id: dev-setup title: Basic Setup sidebar_label: Basic Setup --- @@ -450,7 +449,7 @@ This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can tak :::info If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code. -Once your container is restarted, proceed to [Building and Flashing](./dev-build.md). +Once your container is restarted, proceed to [Building and Flashing](./dev-build-flash.md). ::: #### Export Zephyr™ Core diff --git a/docs/docs/dev-tests.md b/docs/docs/dev-tests.md index d44c4a0..98381d7 100644 --- a/docs/docs/dev-tests.md +++ b/docs/docs/dev-tests.md @@ -1,5 +1,4 @@ --- -id: dev-tests title: Tests sidebar_label: Tests --- diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 5a73110..3822c0d 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -1,5 +1,4 @@ --- -id: faq title: FAQs sidebar_label: FAQs --- diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index f9a2894..c4c16c3 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -1,5 +1,4 @@ --- -id: keymaps title: Keymaps & Behaviors sidebar_label: Keymaps --- diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 6df6019..b142bda 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -1,5 +1,4 @@ --- -id: hardware title: Supported Hardware sidebar_label: Supported Hardware --- diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 8edc313..c76e4b7 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -1,5 +1,4 @@ --- -id: intro title: Introduction to ZMK sidebar_label: Introduction slug: / diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index c45cfcc..f11d02e 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -1,5 +1,4 @@ --- -id: troubleshooting title: Troubleshooting sidebar_title: Troubleshooting --- diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index cdc82ca..703e118 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -1,5 +1,4 @@ --- -id: user-setup title: Installing ZMK sidebar_label: Installing ZMK --- -- cgit v1.2.3