diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md index 73087fb8..4d119ade 100644 --- a/docs/blog/2021-07-17-zephyr-2-5.md +++ b/docs/blog/2021-07-17-zephyr-2-5.md @@ -60,7 +60,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) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/local-toolchain/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 index 193256a7..15a79500 100644 --- a/docs/blog/2022-04-02-zephyr-3-0.md +++ b/docs/blog/2022-04-02-zephyr-3-0.md @@ -61,7 +61,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) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/local-toolchain/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 index f0f54a96..55faeb41 100644 --- a/docs/blog/2022-04-10-zmk-sotf-5.md +++ b/docs/blog/2022-04-10-zmk-sotf-5.md @@ -219,7 +219,7 @@ This can be useful to be sure that lowering brightness doesn't set the brightnes ## Board/Shield Metadata -[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our +[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our more nuanced GH Actions automation for testing changes to ZMK. ## Coming Soon! diff --git a/docs/blog/2023-04-06-zephyr-3-2.md b/docs/blog/2023-04-06-zephyr-3-2.md index 21d3816d..a7d72402 100644 --- a/docs/blog/2023-04-06-zephyr-3-2.md +++ b/docs/blog/2023-04-06-zephyr-3-2.md @@ -86,7 +86,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) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/local-toolchain/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/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md index 441c0233..609425ee 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -173,7 +173,7 @@ For users or future contributors that might want to dive into writing their own #### Shield interconnects -[petejohanson] updated the [new shield guide](/docs/development/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607). +[petejohanson] updated the [new shield guide](/docs/development/hardware-integration/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607). #### Bluetooth feature page diff --git a/docs/blog/2024-02-09-zephyr-3-5.md b/docs/blog/2024-02-09-zephyr-3-5.md index 8b3c941a..2362829e 100644 --- a/docs/blog/2024-02-09-zephyr-3-5.md +++ b/docs/blog/2024-02-09-zephyr-3-5.md @@ -69,7 +69,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) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) +- Run the updated [toolchain installation](/docs/development/local-toolchain/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/config/index.md b/docs/docs/config/index.md index 409b1f04..354633a1 100644 --- a/docs/docs/config/index.md +++ b/docs/docs/config/index.md @@ -64,7 +64,7 @@ ZMK will search the shield folder for the following config files _in addition_ t Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders. -For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/new-shield.mdx) guide. +For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/hardware-integration/new-shield.mdx) guide. ## Kconfig Files diff --git a/docs/docs/config/kscan.md b/docs/docs/config/kscan.md index af4a63fe..b8a3660b 100644 --- a/docs/docs/config/kscan.md +++ b/docs/docs/config/kscan.md @@ -344,7 +344,7 @@ Transforms should be used any time the physical layout of a keyboard's keys does Transforms can also be used for keyboards with multiple layouts. You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps. -See the [new shield guide](../development/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform. +See the [new shield guide](../development/hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform. ### Devicetree diff --git a/docs/docs/customization.md b/docs/docs/customization.md index 638ddbfc..e35bb426 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -40,9 +40,9 @@ 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/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). +It is also possible to build firmware locally on your computer by following the [toolchain setup](development/local-toolchain/setup/index.md) and +[building instructions](development/local-toolchain/build-flash.mdx), which includes pointers to +[building using your `zmk-config` folder](development/local-toolchain/build-flash.mdx#building-from-zmk-config-folder). ::: ## Flashing Your Changes diff --git a/docs/docs/development/clean-room.md b/docs/docs/development/contributing/clean-room.md similarity index 100% rename from docs/docs/development/clean-room.md rename to docs/docs/development/contributing/clean-room.md diff --git a/docs/docs/development/documentation.md b/docs/docs/development/contributing/documentation.md similarity index 96% rename from docs/docs/development/documentation.md rename to docs/docs/development/contributing/documentation.md index 169642ba..5bca6303 100644 --- a/docs/docs/development/documentation.md +++ b/docs/docs/development/contributing/documentation.md @@ -3,6 +3,10 @@ title: Documentation sidebar_label: Documentation --- +:::danger +Before reading this section, it is **vital** that you read through our [clean room policy](clean-room.md). +::: + This document outlines how to test your documentation changes locally and prepare the changes for a pull request. The documentation is written with [Docusaurus](https://docusaurus.io/). The ZMK source code has all of the necessary Docusaurus dependencies included, but referencing their documentation can be helpful at times. diff --git a/docs/docs/development/boards-shields-keymaps.md b/docs/docs/development/hardware-integration/boards-shields-keymaps.md similarity index 96% rename from docs/docs/development/boards-shields-keymaps.md rename to docs/docs/development/hardware-integration/boards-shields-keymaps.md index e936f992..c6e141b9 100644 --- a/docs/docs/development/boards-shields-keymaps.md +++ b/docs/docs/development/hardware-integration/boards-shields-keymaps.md @@ -11,7 +11,7 @@ The foundational elements needed to get a specific keyboard working with ZMK can - A keymap, which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers. These three core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that -keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](../faq.md#why-boards-and-shields-why-not-just-keyboard). +keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](../../faq.md#why-boards-and-shields-why-not-just-keyboard). ## Self-Contained Keyboard @@ -34,7 +34,7 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck ## Pro Micro Compatible Keyboard -![Labelled Pro Micro pins](../assets/interconnects/pro_micro/pinout.png) +![Labelled Pro Micro pins](../../assets/interconnects/pro_micro/pinout.png) For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places in the _shield_ definition for that keyboard, allowing users to diff --git a/docs/docs/development/hardware-metadata-files.md b/docs/docs/development/hardware-integration/hardware-metadata-files.md similarity index 100% rename from docs/docs/development/hardware-metadata-files.md rename to docs/docs/development/hardware-integration/hardware-metadata-files.md diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx similarity index 89% rename from docs/docs/development/new-shield.mdx rename to docs/docs/development/hardware-integration/new-shield.mdx index 2ea23150..6d592161 100644 --- a/docs/docs/development/new-shield.mdx +++ b/docs/docs/development/hardware-integration/new-shield.mdx @@ -4,11 +4,15 @@ title: New Keyboard Shield import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -import KeymapExampleFile from "../keymap-example-file.md"; +import KeymapExampleFile from "../../keymap-example-file.md"; import InterconnectTabs from "@site/src/components/interconnect-tabs"; import Metadata from "@site/src/data/hardware-metadata.json"; +:::danger +Before reading this section, it is **vital** that you read through our [clean room policy](../contributing/clean-room.md). +::: + ## Overview This guide will walk through the steps necessary to add ZMK support for a keyboard that uses an add-on MCU board (e.g. Pro Micro compatible) to provide the microprocessor. @@ -29,7 +33,7 @@ The high level steps are: It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. :::note -ZMK support for [split keyboards](../features/split-keyboards.md) requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. +ZMK support for [split keyboards](../../features/split-keyboards.md) requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. ::: ## New Zephyr Module Repository @@ -60,13 +64,6 @@ Neither of these should be moved out of their parent directory. The other files ## New Shield Directory -:::note -This guide describes how to add a shield to an independently managed Zephyr module repository. This is the -preferred way to handle boards and shields moving forward in ZMK, although the tooling to make this easier -for users is still improving. ZMK does have a collection of boards/shields in the ZMK main repository, which are planned to be phased out, but until that is complete, there _may_ be a few select scenarios where adding your keyboard to ZMK itself is preferred. Due the volume of PRs and the focus of ZMK development not being merging of keyboard PRs, you are highly encouraged to use an out-of-tree Zephyr module repository to manage your definitions. Should you choose to try to get your keyboard included in ZMK main repository, the paths in the rest of the guide would be nested under the `app/` folder there instead. For example, `boards/shields/` should now be -`app/boards/shields/`. -::: - Shields in Zephyr module "board root" go into the `boards/shields/` directory; that means the new shield directory in your module repository should be: ```bash @@ -76,7 +73,7 @@ mkdir boards/shields/ ## Base Kconfig Files :::tip[Example shields] -You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../hardware.mdx) in order to copy and modify as a starting point. +You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../../hardware.mdx) in order to copy and modify as a starting point. ::: There are two required Kconfig files that need to be created for your new keyboard @@ -95,7 +92,7 @@ config SHIELD_MY_BOARD Kconfig uses only commas for delimiters, and keeps all whitespaces in the function call. Therefore do not add a whitespace after the comma when configuring your shield as this would be treated as  my_board (with a leading whitespace) and will cause issues. ::: -This will make sure that a new configuration value named `SHIELD_MY_BOARD` is set to true whenever `my_board` is used as the shield name, either as the `SHIELD` variable [in a local build](build-flash.mdx) or in your `build.yaml` file [when using Github Actions](../customization). Note that this configuration value will be used in `Kconfig.defconfig` to set other properties about your shield, so make sure that they match. +This will make sure that a new configuration value named `SHIELD_MY_BOARD` is set to true whenever `my_board` is used as the shield name, either as the `SHIELD` variable [in a local build](../local-toolchain/build-flash.mdx) or in your `build.yaml` file [when using Github Actions](../../customization.md). Note that this configuration value will be used in `Kconfig.defconfig` to set other properties about your shield, so make sure that they match. **For split boards**, you will need to add configurations for the left and right sides. For example, if your split halves are named `my_board_left` and `my_board_right`, it would look like this: @@ -200,7 +197,7 @@ this might look something like: }; ``` -See the [Keyboard Scan configuration documentation](../config/kscan.md) for details on configuring the KSCAN driver. +See the [Keyboard Scan configuration documentation](../../config/kscan.md) for details on configuring the KSCAN driver. @@ -301,7 +298,7 @@ This is exemplified with the iris .overlay files. ``` -See the [Keyboard Scan configuration documentation](../config/kscan.md) for details on configuring the KSCAN driver. +See the [Keyboard Scan configuration documentation](../../config/kscan.md) for details on configuring the KSCAN driver. ### .conf files (Split Shields) @@ -320,7 +317,7 @@ CONFIG_ZMK_SLEEP=y ``` :::note -The shared configuration in `my_awesome_split_board.conf` is only applied when you are building with a [`zmk-config` folder](build-flash#building-from-zmk-config-folder) and when it is present at `config/my_awesome_split_board.conf`. If you are not using a `zmk-config` folder, you will need to include the shared configuration in both `my_awesome_split_board_left.conf` and `my_awesome_split_board_right.conf` files. +The shared configuration in `my_awesome_split_board.conf` is only applied when you are building with a [`zmk-config` folder](../local-toolchain/build-flash.mdx#building-from-zmk-config-folder) and when it is present at `config/my_awesome_split_board.conf`. If you are not using a `zmk-config` folder, you will need to include the shared configuration in both `my_awesome_split_board_left.conf` and `my_awesome_split_board_right.conf` files. ::: @@ -374,7 +371,7 @@ Some important things to note: - `RC(row, column)` is placed sequentially to define what row and column values that position corresponds to. - If you have a keyboard with options for `2u` keys in certain positions, ANSI vs. ISO layouts, or break away portions, define one matrix transform for each possible arrangement to be used in the physical layouts. This will allow the users to select the right layout in their keymap files. -See the [matrix transform section](../config/kscan.md#matrix-transform) in the Keyboard Scan configuration documentation for details and more examples of matrix transforms. +See the [matrix transform section](../../config/kscan.md#matrix-transform) in the Keyboard Scan configuration documentation for details and more examples of matrix transforms. ## Physical Layout @@ -443,7 +440,7 @@ The two `#include` lines at the top of the keymap are required in order to bring ### Keymap Behaviors -For documentation on the available behaviors for use in keymaps, see the [overview page for behaviors](../keymaps/behaviors/index.mdx). +For documentation on the available behaviors for use in keymaps, see the [overview page for behaviors](../../keymaps/behaviors/index.mdx). ## Metadata @@ -469,7 +466,7 @@ siblings: - corne_right ``` -You should place a properly named `foo.zmk.yml` file in the directory next to your other shield values, and fill it out completely and accurately. See [Hardware Metadata Files](/docs/development/hardware-metadata-files) for the full details. +You should place a properly named `foo.zmk.yml` file in the directory next to your other shield values, and fill it out completely and accurately. See [Hardware Metadata Files](hardware-metadata-files.md) for the full details. ## Build File @@ -567,7 +564,7 @@ Once you have defined the encoder sensors, you will have to add them to the list In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap. -In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../config/encoders.md#devicetree) for more details. +In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../../config/encoders.md#devicetree) for more details. @@ -591,7 +588,7 @@ Add the following line to your keymap file to add default encoder behavior bindi sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>; ``` -Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../features/encoders.md) and [Keymaps](../keymaps/index.mdx) documentation pages for more details. +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../../features/encoders.md) and [Keymaps](../../keymaps/index.mdx) documentation pages for more details. @@ -600,7 +597,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/index.md), +Using GitHub Actions to build your new firmware can save you from doing any local [development setup](../local-toolchain/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 .` @@ -612,7 +609,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/index.md) guide first. +To build locally, be sure you've followed the [development setup](../local-toolchain/setup/index.md) guide first. ::: Once you've fully created the new keyboard shield definition, @@ -623,7 +620,7 @@ west build --pristine -b nice_nano_v2 -- -DSHIELD= -DZMK_EXTRA_MODULE # replace with e.g. _left for split keyboards, then repeat for _right ``` -The above build command generates a `build/zephyr/zmk.uf2` file that you can flash using the steps from the following section. See the dedicated [building and flashing page](build-flash.mdx) for more details. +The above build command generates a `build/zephyr/zmk.uf2` file that you can flash using the steps from the following section. See the dedicated [building and flashing page](../local-toolchain/build-flash.mdx) for more details. ### Flashing @@ -642,9 +639,9 @@ west flash ``` Please have a look at documentation specific to -[building and flashing](build-flash.mdx) for additional information. +[building and flashing](../local-toolchain/build-flash.mdx) for additional information. :::note Further testing your keyboard shield without altering the root keymap file can be done with the use of `-DZMK_CONFIG` in your `west build` command, -shown [here](build-flash.mdx#building-from-zmk-config-folder) +shown [here](../local-toolchain/build-flash.mdx#building-from-zmk-config-folder) ::: diff --git a/docs/docs/development/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx similarity index 96% rename from docs/docs/development/build-flash.mdx rename to docs/docs/development/local-toolchain/build-flash.mdx index cfcb39ee..464cf34d 100644 --- a/docs/docs/development/build-flash.mdx +++ b/docs/docs/development/local-toolchain/build-flash.mdx @@ -95,7 +95,7 @@ west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Use ### 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.mdx#github-repo) by adding +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../../user-setup.mdx#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: @@ -109,7 +109,7 @@ The above command must still be invoked from the `zmk/app` directory as noted ab ::: :::warning -If your config is also a [module](../features/modules.mdx), then you should also add the root (the folder in which the `zephyr` folder is found) of your `zmk-config` as an [external module to build with](#building-with-external-modules). +If your config is also a [module](../../features/modules.mdx), then you should also add the root (the folder in which the `zephyr` folder is found) of your `zmk-config` as an [external module to build with](#building-with-external-modules). ::: In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config` diff --git a/docs/docs/development/ide-integration.mdx b/docs/docs/development/local-toolchain/ide-integration.mdx similarity index 100% rename from docs/docs/development/ide-integration.mdx rename to docs/docs/development/local-toolchain/ide-integration.mdx diff --git a/docs/docs/development/posix-board.md b/docs/docs/development/local-toolchain/posix-board.md similarity index 100% rename from docs/docs/development/posix-board.md rename to docs/docs/development/local-toolchain/posix-board.md diff --git a/docs/docs/development/pre-commit.md b/docs/docs/development/local-toolchain/pre-commit.md similarity index 100% rename from docs/docs/development/pre-commit.md rename to docs/docs/development/local-toolchain/pre-commit.md diff --git a/docs/docs/development/setup/docker.md b/docs/docs/development/local-toolchain/setup/docker.md similarity index 95% rename from docs/docs/development/setup/docker.md rename to docs/docs/development/local-toolchain/setup/docker.md index 767331e4..8d9f94bc 100644 --- a/docs/docs/development/setup/docker.md +++ b/docs/docs/development/local-toolchain/setup/docker.md @@ -25,7 +25,7 @@ git clone https://github.com/zmkfirmware/zmk.git Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up: -![VS Code Dev Container Configuration Alert](../../assets/dev-setup/vscode_devcontainer.png) +![VS Code Dev Container Configuration Alert](../../../assets/dev-setup/vscode_devcontainer.png) Click `Reopen in Container` in order to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing `ctrl+shift+p` and selecting `Remote: Show Remote Menu`. diff --git a/docs/docs/development/setup/index.md b/docs/docs/development/local-toolchain/setup/index.md similarity index 80% rename from docs/docs/development/setup/index.md rename to docs/docs/development/local-toolchain/setup/index.md index 5c795fa2..71cc051e 100644 --- a/docs/docs/development/setup/index.md +++ b/docs/docs/development/local-toolchain/setup/index.md @@ -11,10 +11,10 @@ We recommend reading through the setup process before following it step by step, There are two ways to set up the ZMK development environment: -- [Docker](/docs/development/setup/docker): \ +- [Docker](docker.md): \ A self-contained development environment. It uses the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach may be easier to set up for some operating systems. No toolchain or dependencies are necessary when using Docker; the container image has the toolchain installed and set up to use. -- [Native](/docs/development/setup/native):\ +- [Native](native.mdx):\ This uses your operating system directly. Usually runs slightly faster than the Docker approach, and can be preferable for users who already have the dependencies on their system. -Please see the [Docker](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup. +Please see the [Docker](docker.md) instructions or [native](native.mdx) instructions to continue setup. diff --git a/docs/docs/development/setup/native.mdx b/docs/docs/development/local-toolchain/setup/native.mdx similarity index 100% rename from docs/docs/development/setup/native.mdx rename to docs/docs/development/local-toolchain/setup/native.mdx diff --git a/docs/docs/development/tests.md b/docs/docs/development/local-toolchain/tests.md similarity index 100% rename from docs/docs/development/tests.md rename to docs/docs/development/local-toolchain/tests.md diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx index 65f0f60b..3d50b821 100644 --- a/docs/docs/development/new-behavior.mdx +++ b/docs/docs/development/new-behavior.mdx @@ -1,11 +1,15 @@ --- title: New Behavior -sidebar_label: New Behavior +sidebar_label: New Behavior Guide --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; +:::danger +Before reading this section, it is **vital** that you read through our [clean room policy](./contributing/clean-room.md). +::: + ## Overview This document outlines how to develop a [behavior](../keymaps/behaviors/index.mdx) for ZMK and prepare the changes for a pull request. @@ -432,7 +436,7 @@ Zephyr currently does not support logging over Bluetooth, so any use of the seri :::info -- See [Tests](tests.md) for more information on how to create virtual test sets. +- See [Tests](local-toolchain/tests.md) for more information on how to create virtual test sets. - For hardware-based testing, see [USB Logging](usb-logging.mdx). ::: @@ -450,7 +454,7 @@ Consider the following prompts when writing documentation for new behaviors: Consider also including visual aids alongside written documentation if it adds clarity. :::info -See [Documentation](documentation.md) for more information on writing, testing, and formatting ZMK documentation. +See [Documentation](contributing/documentation.md) for more information on writing, testing, and formatting ZMK documentation. ::: ## Submitting a Pull Request diff --git a/docs/docs/development/studio-rpc-protocol.md b/docs/docs/development/studio-rpc-protocol.md index f352a174..da737a13 100644 --- a/docs/docs/development/studio-rpc-protocol.md +++ b/docs/docs/development/studio-rpc-protocol.md @@ -8,6 +8,10 @@ ZMK Studio is still in active development, and the below information is for deve ::: +:::danger +Before reading this section, it is **vital** that you read through our [clean room policy](./contributing/clean-room.md). +::: + ## Overview The ZMK Studio UI communicates with ZMK devices using a custom RPC protocol developed to be robust and reliable, while remaining simple and easy to extend with future enhancements. diff --git a/docs/docs/features/encoders.md b/docs/docs/features/encoders.md index cc5bb708..046973f4 100644 --- a/docs/docs/features/encoders.md +++ b/docs/docs/features/encoders.md @@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig ## Adding Encoder Support -See the [New Keyboard Shield](../development/new-shield.mdx#encoders) documentation for how to add or modify additional encoders to your shield. +See the [New Keyboard Shield](../development/hardware-integration/new-shield.mdx#encoders) documentation for how to add or modify additional encoders to your shield. diff --git a/docs/docs/features/modules.mdx b/docs/docs/features/modules.mdx index acab84c2..5cc6e3d1 100644 --- a/docs/docs/features/modules.mdx +++ b/docs/docs/features/modules.mdx @@ -113,7 +113,7 @@ manifest: ### Building Locally -To add a module to your build when building locally, you will need to clone/copy said module into your local file tree. You can then build using the module as described in [Building with External Modules](../development/build-flash.mdx#building-with-external-modules). +To add a module to your build when building locally, you will need to clone/copy said module into your local file tree. You can then build using the module as described in [Building with External Modules](../development/local-toolchain/build-flash.mdx#building-with-external-modules). ## Beta Testing @@ -191,4 +191,4 @@ manifest: ### Building Locally -When building from a pull request locally, you'll need to [perform the local user setup](../development/setup/index.md), but using the repository of the pull request rather than the official ZMK repository. You can then [build and flash](../development/build-flash.mdx) as usual. +When building from a pull request locally, you'll need to [perform the local user setup](../development/local-toolchain/setup/index.md), but using the repository of the pull request rather than the official ZMK repository. You can then [build and flash](../development/local-toolchain/build-flash.mdx) as usual. diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md index 7421d1d6..8c69d51a 100644 --- a/docs/docs/features/split-keyboards.md +++ b/docs/docs/features/split-keyboards.md @@ -30,7 +30,7 @@ You can refer to the [power profiler](/power-profiler) to see battery life estim ### Configuration -The [new shield guide](../development/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part. +The [new shield guide](../development/hardware-integration/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part. Also see the reference section on [split keyboards configuration](../config/system.md#split-keyboards) where the relevant symbols include `CONFIG_ZMK_SPLIT` that enables the feature, `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` which sets the central role and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` that sets the number of peripherals. diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx index 4e452868..09f98c84 100644 --- a/docs/docs/hardware.mdx +++ b/docs/docs/hardware.mdx @@ -55,4 +55,4 @@ Please see pages under the "Features" header in the sidebar for details. {/* prettier-ignore */} Contributing -If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield.mdx) documentation and note the [clean room design requirements](development/clean-room.md). +If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/contributing/clean-room.md). diff --git a/docs/docs/user-setup-cli.mdx b/docs/docs/user-setup-cli.mdx index ecb0dd23..d486d763 100644 --- a/docs/docs/user-setup-cli.mdx +++ b/docs/docs/user-setup-cli.mdx @@ -187,7 +187,7 @@ Run `zmk keyboard list` to print a list of supported keyboard hardware. If ZMK doesn't support your keyboard yet, you can run `zmk keyboard new` to create a new keyboard from a template. -This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](development/new-shield.mdx) guide for how to finish writing the keyboard files. +This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) guide for how to finish writing the keyboard files. ### Module Management diff --git a/docs/docs/user-setup.mdx b/docs/docs/user-setup.mdx index fb83ba62..9f0dd1ce 100644 --- a/docs/docs/user-setup.mdx +++ b/docs/docs/user-setup.mdx @@ -112,7 +112,7 @@ If you are building firmware for a new keyboard that is not included in the buil list of keyboards, you can choose any keyboard from the list that is similar to yours (e.g. in terms of unibody/split and [onboard controller](hardware.mdx#onboard) / [composite](hardware.mdx#composite)) to generate the repository, -and edit / add necessary files. You can follow the [new shield guide](development/new-shield.mdx) if you are adding support for a composite keyboard. +and edit / add necessary files. You can follow the [new shield guide](development/hardware-integration/new-shield.mdx) if you are adding support for a composite keyboard. ::: ### MCU Board Selection diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index b4e3449a..57528240 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -81,7 +81,7 @@ module.exports = { }, { label: "Development", - to: "docs/development/setup", + to: "docs/development/contributing/clean-room", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index c52d6f09..da619e5e 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -116,36 +116,53 @@ module.exports = { }, { Development: [ - "development/clean-room", - "development/pre-commit", - "development/documentation", { type: "category", - label: "Setup", - link: { - type: "doc", - id: "development/setup/index", - }, + label: "Hardware Integration", collapsed: true, - items: ["development/setup/docker", "development/setup/native"], - }, - "development/build-flash", - "development/boards-shields-keymaps", - "development/posix-board", - "development/tests", - "development/usb-logging", - "development/ide-integration", - "development/studio-rpc-protocol", - { - type: "category", - label: "Guides", - collapsed: false, items: [ - "development/new-shield", - "development/hardware-metadata-files", - "development/new-behavior", + "development/hardware-integration/new-shield", + "development/hardware-integration/hardware-metadata-files", + "development/hardware-integration/boards-shields-keymaps", ], }, + { + type: "category", + label: "Contributing", + collapsed: true, + items: [ + "development/contributing/clean-room", + "development/contributing/documentation", + ], + }, + { + type: "category", + label: "Local Toolchain", + collapsed: true, + items: [ + { + type: "category", + label: "Setup", + link: { + type: "doc", + id: "development/local-toolchain/setup/index", + }, + collapsed: true, + items: [ + "development/local-toolchain/setup/docker", + "development/local-toolchain/setup/native", + ], + }, + "development/local-toolchain/build-flash", + "development/local-toolchain/pre-commit", + "development/local-toolchain/ide-integration", + "development/local-toolchain/tests", + "development/local-toolchain/posix-board", + ], + }, + "development/usb-logging", + "development/studio-rpc-protocol", + "development/new-behavior", ], }, ], diff --git a/docs/static/_redirects b/docs/static/_redirects index 2113e0d9..f5e8da26 100644 --- a/docs/static/_redirects +++ b/docs/static/_redirects @@ -5,4 +5,16 @@ /docs/features/encoders /docs/keymaps/encoders 301 /docs/codes/modifiers /docs/keymaps/modifiers 301 /docs/codes/* /docs/keymaps/list-of-keycodes 301 -/docs/features/beta-testing /docs/features/modules#beta-testing 301 \ No newline at end of file +/docs/features/beta-testing /docs/features/modules#beta-testing 301 +/docs/development/setup /docs/development/local-toolchain/setup 301 +/docs/development/boards-shields-keymaps /docs/development/hardware-integration/boards-shields-keymaps 301 +/docs/development/hardware-metadata-files /docs/development/hardware-integration/hardware-metadata-files 301 +/docs/development/clean-room /docs/development/contributing/clean-room 301 +/docs/development/documentation /docs/development/contributing/documentation 301 +/docs/development/new-shield /docs/development/hardware-integration/new-shield 301 +/docs/development/build-flash /docs/development/local-toolchain/build-flash 301 +/docs/development/ide-integration /docs/development/local-toolchain/ide-integration 301 +/docs/development/posix-board /docs/development/local-toolchain/posix-board 301 +/docs/development/pre-commit /docs/development/local-toolchain/pre-commit 301 +/docs/development/tests /docs/development/local-toolchain/tests 301 +/docs/development/guides/new-behavior /docs/development/new-behavior 301 \ No newline at end of file