From 8e15b5fa968613cb8d3409ededb35d8f3cb610e1 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Sat, 24 Aug 2024 09:37:33 +0200 Subject: [PATCH 01/16] Added advanced guides page --- docs/docs/advanced-guides/index.md | 12 ++++++++++++ docs/sidebars.js | 10 ++++++++++ 2 files changed, 22 insertions(+) create mode 100644 docs/docs/advanced-guides/index.md diff --git a/docs/docs/advanced-guides/index.md b/docs/docs/advanced-guides/index.md new file mode 100644 index 00000000..e56cfebe --- /dev/null +++ b/docs/docs/advanced-guides/index.md @@ -0,0 +1,12 @@ +--- +title: Advanced Guides +sidebar_label: Advanced Guides +--- + +import DocCardList from "@theme/DocCardList"; + +ZMK, being built on [Zephyr™](https://zephyrproject.org/), is very modular and flexible. This allows users to combine features, flags, and properties to "construct" features in ZMK, without the need to modify the underlying source code. + +These pages are a collection of guides for users who want a _bit_ more out of their ZMK devices, without the need to delve into the [Zephyr™](https://zephyrproject.org/) documentation. Guides aimed at keyboard designers are also found under this section. + + diff --git a/docs/sidebars.js b/docs/sidebars.js index c52d6f09..0dc1b852 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -114,6 +114,16 @@ module.exports = { "config/system", ], }, + { + type: "category", + label: "Advanced Guides", + link: { + type: "doc", + id: "advanced-guides/index", + }, + collapsed: true, + items: [], + }, { Development: [ "development/clean-room", From f01cbc993eceab436604b0c6a7a411baad0ead84 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Sat, 24 Aug 2024 09:45:17 +0200 Subject: [PATCH 02/16] Added making modules page --- docs/docs/advanced-guides/making-modules.mdx | 147 +++++++++++++++++++ docs/sidebars.js | 2 +- 2 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 docs/docs/advanced-guides/making-modules.mdx diff --git a/docs/docs/advanced-guides/making-modules.mdx b/docs/docs/advanced-guides/making-modules.mdx new file mode 100644 index 00000000..db464294 --- /dev/null +++ b/docs/docs/advanced-guides/making-modules.mdx @@ -0,0 +1,147 @@ +--- +title: Making ZMK Modules +sidebar_label: Making ZMK Modules +--- + +[ZMK modules](../features/modules.mdx) are the recommended method of adding content to ZMK, whenever it is possible. This page will guide you through creating a module for ZMK, beginning from an empty git repository. Distinction is made between modules used for different purposes: + +- Modules containing one or more keyboard-related definitions (boards, shields, interconnects, etc.) +- Modules containing behaviors & features +- Modules containing drivers + +In general, it is recommended that you create one module per item - one behavior per module, one driver per module, etc. Keyboard definitions can be an exception: Multiple keyboards belonging to the same "family" can exist within the same module. Here "family" could refer to a series with similar names, or even all keyboards from a particular designer. + +:::tip +For keyboard-related modules specifically, the simplest approach is to use the [unified zmk config template](https://github.com/zmkfirmware/unified-zmk-config-template) as a template, and then make the appropriate edits. +::: + +## Zephyr Module File + +A repository is made into a module with the presence of a `/zephyr/module.yaml` file. This file describes the module. A full description of this file can be found in the [Zephyr documentation](https://docs.zephyrproject.org/3.5.0/develop/modules.html), the most commonly used parts of which are presented here. + +### Module Name + +A name can be assigned to the module through the use of the `name` property: + +```yaml title="/zephyr/module.yaml" +name: +``` + +Your module _can_ function without being named, but we recommend that you give it a name for organisational purposes. Names should be lowercase alphanumeric and `-` only. + +The naming convention we recommend is `zmk---`, where: + +- `type` is one of `keyboards`, `behavior`, `driver`, `feature` +- `username` is a username that you go by, or alternatively the name of your company/organisation +- `description` is a short description of what the module contains + +Do note that the name denoted in the `module.yaml` file **does not** have to be the same as the name of the module's git repository. + +For example: + +```yaml title="cirque-input-module/zephyr/module.yaml" +name: `zmk-driver-petejohanson-cirque-pinnacle` +``` + +### Build Configuration + +The `build` property is used to specify a number of settings to be used when including your module in the final build. + +#### Dependencies + +The `depends` child property is used to specify a list of modules which the module depends on. The dependencies are referred to by their [module name](#module-name). + +```yaml title="/zephyr/module.yaml" +build: + depends: + - +``` + +#### Build files + +The `cmake` and `kconfig` child properties are used to identify the `CMakeLists.txt` and `Kconfig` which are used to build the module. + +- `cmake` points to the _directory_ in which the `CMakeLists.txt` is found. +- `kconfig` points to the _path_ of the `Kconfig` file. + +Here's an example where both of these files are found at the root of the module: + +```yaml title="/zephyr/module.yaml" +build: + cmake: . + kconfig: Kconfig +``` + +#### Build settings + +Additional build settings fall under the `settings` property, which itself is a child of the `build` property. Particularly relevant settings are: + +- `board_root` which points to a directory containing a `boards` directory, which contains additional board/shield definitions. +- `dts_root` which points to a directory containing a `dts` directory, which contains additional devicetree bindings. + +A full list of build settings can be found [here](https://docs.zephyrproject.org/3.5.0/develop/modules.html#build-settings). Here's an example where both of these directories are found at the root of the module: + +```yaml title="/zephyr/module.yaml" +build: + settings: + board_root: . + dts_root: . +``` + +### Examples + +The following are some examples of `module.yaml` files as they are commonly used in ZMK. + +#### Keyboard module example + +```yaml title="lpgalaxy-keyboards/zephyr/module.yaml" +name: "zmk-keyboards-lpgalaxy" +build: + settings: + board_root: . +``` + +#### Behavior module example + +```yaml title="auto-layer-module/zephyr/module.yaml" +name: "zmk-behavior-urob-autolayer" +build: + cmake: . + settings: + dts_root: . +``` + +## Optional Files + +While the `zephyr/module.yaml` file is the only file _necessary_ for a module, there are a number of files which can be helpful to have. + +### West Manifest + +A [West Manifest](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html) file can be included to specify the locations of module dependencies, so that they can be automatically discovered and imported when your module is used. The typical format used in ZMK-related content is + +```yaml title="config/west.yml" +manifest: + remotes: + - name: zmkfirmware + url-base: https://github.com/zmkfirmware + # Additional modules containing boards/shields/custom code can be listed here as well + # See https://docs.zephyrproject.org/3.2.0/develop/west/manifest.html#projects + projects: + - name: zmk + remote: zmkfirmware + revision: main + import: app/west.yml + self: + path: config +``` + +The above file describes a west manifest file called `west.yml` located in a directory named `config`, naming `zmk` as a module dependency. +See the [modules feature page](../features/modules.mdx) for additional information on using west manifest files. + +### GitHub Actions + +If your module contains keyboard definitions and is hosted on GitHub, it may be useful to include a `build.yaml` in the root of your directory and the standard `.github/workflows/build.yml` file used to build keyboard firmware via GitHub actions. This would allow potential users to simply download the firmware from your module, and can be particularly useful as [ZMK Studio](../development/studio-rpc-protocol.md) increases in use. + +### Other Files + +It is recommended that you include a `LICENSE` file and a `README.md`, as is typical of Git repositories. diff --git a/docs/sidebars.js b/docs/sidebars.js index 0dc1b852..eec32638 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -122,7 +122,7 @@ module.exports = { id: "advanced-guides/index", }, collapsed: true, - items: [], + items: ["advanced-guides/making-modules"], }, { Development: [ From 9519d0cece6d3785cb67b02ee9aff0e03e217ec6 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Fri, 30 Aug 2024 14:14:00 +0200 Subject: [PATCH 03/16] Refactoring of the development section --- docs/docs/advanced-guides/index.md | 12 -- docs/docs/advanced-guides/making-modules.mdx | 147 ------------------ .../{ => contributing}/clean-room.md | 0 .../{ => contributing}/documentation.md | 0 .../boards-shields-keymaps.md | 0 .../hardware-metadata-files.md | 0 .../development/hardware-integration/index.md | 12 ++ .../{ => hardware-integration}/new-shield.mdx | 0 .../{ => local-toolchain}/build-flash.mdx | 0 .../{ => local-toolchain}/ide-integration.mdx | 0 .../{ => local-toolchain}/posix-board.md | 0 .../{ => local-toolchain}/pre-commit.md | 0 .../{ => local-toolchain}/setup/docker.md | 0 .../{ => local-toolchain}/setup/index.md | 0 .../{ => local-toolchain}/setup/native.mdx | 0 .../{ => local-toolchain}/tests.md | 0 .../{ => local-toolchain}/usb-logging.mdx | 0 docs/docs/development/new-behavior.mdx | 2 +- docs/sidebars.js | 68 ++++---- 19 files changed, 53 insertions(+), 188 deletions(-) delete mode 100644 docs/docs/advanced-guides/index.md delete mode 100644 docs/docs/advanced-guides/making-modules.mdx rename docs/docs/development/{ => contributing}/clean-room.md (100%) rename docs/docs/development/{ => contributing}/documentation.md (100%) rename docs/docs/development/{ => hardware-integration}/boards-shields-keymaps.md (100%) rename docs/docs/development/{ => hardware-integration}/hardware-metadata-files.md (100%) create mode 100644 docs/docs/development/hardware-integration/index.md rename docs/docs/development/{ => hardware-integration}/new-shield.mdx (100%) rename docs/docs/development/{ => local-toolchain}/build-flash.mdx (100%) rename docs/docs/development/{ => local-toolchain}/ide-integration.mdx (100%) rename docs/docs/development/{ => local-toolchain}/posix-board.md (100%) rename docs/docs/development/{ => local-toolchain}/pre-commit.md (100%) rename docs/docs/development/{ => local-toolchain}/setup/docker.md (100%) rename docs/docs/development/{ => local-toolchain}/setup/index.md (100%) rename docs/docs/development/{ => local-toolchain}/setup/native.mdx (100%) rename docs/docs/development/{ => local-toolchain}/tests.md (100%) rename docs/docs/development/{ => local-toolchain}/usb-logging.mdx (100%) diff --git a/docs/docs/advanced-guides/index.md b/docs/docs/advanced-guides/index.md deleted file mode 100644 index e56cfebe..00000000 --- a/docs/docs/advanced-guides/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Advanced Guides -sidebar_label: Advanced Guides ---- - -import DocCardList from "@theme/DocCardList"; - -ZMK, being built on [Zephyr™](https://zephyrproject.org/), is very modular and flexible. This allows users to combine features, flags, and properties to "construct" features in ZMK, without the need to modify the underlying source code. - -These pages are a collection of guides for users who want a _bit_ more out of their ZMK devices, without the need to delve into the [Zephyr™](https://zephyrproject.org/) documentation. Guides aimed at keyboard designers are also found under this section. - - diff --git a/docs/docs/advanced-guides/making-modules.mdx b/docs/docs/advanced-guides/making-modules.mdx deleted file mode 100644 index db464294..00000000 --- a/docs/docs/advanced-guides/making-modules.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Making ZMK Modules -sidebar_label: Making ZMK Modules ---- - -[ZMK modules](../features/modules.mdx) are the recommended method of adding content to ZMK, whenever it is possible. This page will guide you through creating a module for ZMK, beginning from an empty git repository. Distinction is made between modules used for different purposes: - -- Modules containing one or more keyboard-related definitions (boards, shields, interconnects, etc.) -- Modules containing behaviors & features -- Modules containing drivers - -In general, it is recommended that you create one module per item - one behavior per module, one driver per module, etc. Keyboard definitions can be an exception: Multiple keyboards belonging to the same "family" can exist within the same module. Here "family" could refer to a series with similar names, or even all keyboards from a particular designer. - -:::tip -For keyboard-related modules specifically, the simplest approach is to use the [unified zmk config template](https://github.com/zmkfirmware/unified-zmk-config-template) as a template, and then make the appropriate edits. -::: - -## Zephyr Module File - -A repository is made into a module with the presence of a `/zephyr/module.yaml` file. This file describes the module. A full description of this file can be found in the [Zephyr documentation](https://docs.zephyrproject.org/3.5.0/develop/modules.html), the most commonly used parts of which are presented here. - -### Module Name - -A name can be assigned to the module through the use of the `name` property: - -```yaml title="/zephyr/module.yaml" -name: -``` - -Your module _can_ function without being named, but we recommend that you give it a name for organisational purposes. Names should be lowercase alphanumeric and `-` only. - -The naming convention we recommend is `zmk---`, where: - -- `type` is one of `keyboards`, `behavior`, `driver`, `feature` -- `username` is a username that you go by, or alternatively the name of your company/organisation -- `description` is a short description of what the module contains - -Do note that the name denoted in the `module.yaml` file **does not** have to be the same as the name of the module's git repository. - -For example: - -```yaml title="cirque-input-module/zephyr/module.yaml" -name: `zmk-driver-petejohanson-cirque-pinnacle` -``` - -### Build Configuration - -The `build` property is used to specify a number of settings to be used when including your module in the final build. - -#### Dependencies - -The `depends` child property is used to specify a list of modules which the module depends on. The dependencies are referred to by their [module name](#module-name). - -```yaml title="/zephyr/module.yaml" -build: - depends: - - -``` - -#### Build files - -The `cmake` and `kconfig` child properties are used to identify the `CMakeLists.txt` and `Kconfig` which are used to build the module. - -- `cmake` points to the _directory_ in which the `CMakeLists.txt` is found. -- `kconfig` points to the _path_ of the `Kconfig` file. - -Here's an example where both of these files are found at the root of the module: - -```yaml title="/zephyr/module.yaml" -build: - cmake: . - kconfig: Kconfig -``` - -#### Build settings - -Additional build settings fall under the `settings` property, which itself is a child of the `build` property. Particularly relevant settings are: - -- `board_root` which points to a directory containing a `boards` directory, which contains additional board/shield definitions. -- `dts_root` which points to a directory containing a `dts` directory, which contains additional devicetree bindings. - -A full list of build settings can be found [here](https://docs.zephyrproject.org/3.5.0/develop/modules.html#build-settings). Here's an example where both of these directories are found at the root of the module: - -```yaml title="/zephyr/module.yaml" -build: - settings: - board_root: . - dts_root: . -``` - -### Examples - -The following are some examples of `module.yaml` files as they are commonly used in ZMK. - -#### Keyboard module example - -```yaml title="lpgalaxy-keyboards/zephyr/module.yaml" -name: "zmk-keyboards-lpgalaxy" -build: - settings: - board_root: . -``` - -#### Behavior module example - -```yaml title="auto-layer-module/zephyr/module.yaml" -name: "zmk-behavior-urob-autolayer" -build: - cmake: . - settings: - dts_root: . -``` - -## Optional Files - -While the `zephyr/module.yaml` file is the only file _necessary_ for a module, there are a number of files which can be helpful to have. - -### West Manifest - -A [West Manifest](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html) file can be included to specify the locations of module dependencies, so that they can be automatically discovered and imported when your module is used. The typical format used in ZMK-related content is - -```yaml title="config/west.yml" -manifest: - remotes: - - name: zmkfirmware - url-base: https://github.com/zmkfirmware - # Additional modules containing boards/shields/custom code can be listed here as well - # See https://docs.zephyrproject.org/3.2.0/develop/west/manifest.html#projects - projects: - - name: zmk - remote: zmkfirmware - revision: main - import: app/west.yml - self: - path: config -``` - -The above file describes a west manifest file called `west.yml` located in a directory named `config`, naming `zmk` as a module dependency. -See the [modules feature page](../features/modules.mdx) for additional information on using west manifest files. - -### GitHub Actions - -If your module contains keyboard definitions and is hosted on GitHub, it may be useful to include a `build.yaml` in the root of your directory and the standard `.github/workflows/build.yml` file used to build keyboard firmware via GitHub actions. This would allow potential users to simply download the firmware from your module, and can be particularly useful as [ZMK Studio](../development/studio-rpc-protocol.md) increases in use. - -### Other Files - -It is recommended that you include a `LICENSE` file and a `README.md`, as is typical of Git repositories. 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 100% rename from docs/docs/development/documentation.md rename to docs/docs/development/contributing/documentation.md diff --git a/docs/docs/development/boards-shields-keymaps.md b/docs/docs/development/hardware-integration/boards-shields-keymaps.md similarity index 100% rename from docs/docs/development/boards-shields-keymaps.md rename to docs/docs/development/hardware-integration/boards-shields-keymaps.md 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/hardware-integration/index.md b/docs/docs/development/hardware-integration/index.md new file mode 100644 index 00000000..dd828224 --- /dev/null +++ b/docs/docs/development/hardware-integration/index.md @@ -0,0 +1,12 @@ +--- +title: Hardware Integration +sidebar_label: Hardware Integration +--- + +import DocCardList from "@theme/DocCardList"; + +ZMK, being built on [Zephyr™](https://zephyrproject.org/), is very modular and flexible. This allows users to combine features, flags, and properties to "construct" features in ZMK, without the need to modify the underlying source code. + +However, this very same flexibility can be difficult to utilise, thanks to the resulting complexity. This section features guides and informative pages on how to integrate configure, and modify hardware with ZMK; **without** needing to refer to [Zephyr™ documentation](https://docs.zephyrproject.org/3.5.0/index.html) for a majority of cases. + + diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx similarity index 100% rename from docs/docs/development/new-shield.mdx rename to docs/docs/development/hardware-integration/new-shield.mdx diff --git a/docs/docs/development/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx similarity index 100% rename from docs/docs/development/build-flash.mdx rename to docs/docs/development/local-toolchain/build-flash.mdx 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 100% rename from docs/docs/development/setup/docker.md rename to docs/docs/development/local-toolchain/setup/docker.md diff --git a/docs/docs/development/setup/index.md b/docs/docs/development/local-toolchain/setup/index.md similarity index 100% rename from docs/docs/development/setup/index.md rename to docs/docs/development/local-toolchain/setup/index.md 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/usb-logging.mdx b/docs/docs/development/local-toolchain/usb-logging.mdx similarity index 100% rename from docs/docs/development/usb-logging.mdx rename to docs/docs/development/local-toolchain/usb-logging.mdx diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx index 65f0f60b..44439e20 100644 --- a/docs/docs/development/new-behavior.mdx +++ b/docs/docs/development/new-behavior.mdx @@ -1,6 +1,6 @@ --- title: New Behavior -sidebar_label: New Behavior +sidebar_label: New Behavior Guide --- import Tabs from "@theme/Tabs"; diff --git a/docs/sidebars.js b/docs/sidebars.js index eec32638..a053f4b8 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -114,46 +114,58 @@ module.exports = { "config/system", ], }, - { - type: "category", - label: "Advanced Guides", - link: { - type: "doc", - id: "advanced-guides/index", - }, - collapsed: true, - items: ["advanced-guides/making-modules"], - }, { Development: [ - "development/clean-room", - "development/pre-commit", - "development/documentation", + "development/making-modules", + "development/studio-rpc-protocol", + "development/new-behavior", { type: "category", - label: "Setup", + label: "Hardware Integration", link: { type: "doc", - id: "development/setup/index", + id: "development/hardware-integration/index", }, collapsed: true, - items: ["development/setup/docker", "development/setup/native"], + items: [ + "development/hardware-integration/new-shield", + "development/hardware-integration/hardware-metadata-files", + "development/hardware-integration/boards-shields-keymaps", + ], }, - "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, + label: "Contributing", + collapsed: true, items: [ - "development/new-shield", - "development/hardware-metadata-files", - "development/new-behavior", + "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/usb-logging", + "development/local-toolchain/pre-commit", + "development/local-toolchain/ide-integration", + "development/local-toolchain/tests", + "development/local-toolchain/posix-board", ], }, ], From f28c82ac9124fe582efb0112a4bdeec94478cc19 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Fri, 30 Aug 2024 16:50:23 +0200 Subject: [PATCH 04/16] fixed all the links --- docs/blog/2021-07-17-zephyr-2-5.md | 2 +- docs/blog/2022-04-02-zephyr-3-0.md | 2 +- docs/blog/2022-04-10-zmk-sotf-5.md | 2 +- docs/blog/2023-04-06-zephyr-3-2.md | 2 +- docs/blog/2023-10-05-zmk-sotf-6.md | 2 +- docs/blog/2024-02-09-zephyr-3-5.md | 2 +- docs/docs/config/index.md | 2 +- docs/docs/config/kscan.md | 2 +- docs/docs/customization.md | 6 ++-- .../{contributing => }/documentation.md | 0 .../boards-shields-keymaps.md | 4 +-- .../hardware-integration/new-shield.mdx | 34 +++++++++---------- .../{contributing/clean-room.md => index.md} | 0 .../local-toolchain/build-flash.mdx | 4 +-- .../local-toolchain/setup/docker.md | 2 +- .../local-toolchain/setup/index.md | 6 ++-- .../local-toolchain/usb-logging.mdx | 4 +-- docs/docs/development/new-behavior.mdx | 6 ++-- docs/docs/features/encoders.md | 2 +- docs/docs/features/modules.mdx | 4 +-- docs/docs/features/split-keyboards.md | 2 +- docs/docs/hardware.mdx | 2 +- docs/docs/keymaps/behaviors/bluetooth.md | 2 +- .../troubleshooting/connection-issues.mdx | 2 +- docs/docs/user-setup-cli.mdx | 2 +- docs/docs/user-setup.mdx | 2 +- docs/docusaurus.config.js | 2 +- docs/sidebars.js | 24 ++++++------- docs/static/_redirects | 13 ++++++- 29 files changed, 74 insertions(+), 65 deletions(-) rename docs/docs/development/{contributing => }/documentation.md (100%) rename docs/docs/development/{contributing/clean-room.md => index.md} (100%) diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md index 789a644c..4c1e7b2f 100644 --- 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) 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 92e8b33b..17e61000 100644 --- 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) 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 bcefcb46..44d8ecfb 100644 --- a/docs/blog/2022-04-10-zmk-sotf-5.md +++ b/docs/blog/2022-04-10-zmk-sotf-5.md @@ -220,7 +220,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 21058ca9..ca398225 100644 --- 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) 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 5de59407..8f9839fc 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -174,7 +174,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 738f22da..c5084988 100644 --- 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) 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/contributing/documentation.md b/docs/docs/development/documentation.md similarity index 100% rename from docs/docs/development/contributing/documentation.md rename to docs/docs/development/documentation.md diff --git a/docs/docs/development/hardware-integration/boards-shields-keymaps.md b/docs/docs/development/hardware-integration/boards-shields-keymaps.md index e936f992..c6e141b9 100644 --- a/docs/docs/development/hardware-integration/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-integration/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx index 1aaab896..c758ebe1 100644 --- a/docs/docs/development/hardware-integration/new-shield.mdx +++ b/docs/docs/development/hardware-integration/new-shield.mdx @@ -4,7 +4,7 @@ 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"; @@ -29,7 +29,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 @@ -76,7 +76,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 +95,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). 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 +200,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 +301,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 +320,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#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 +374,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 +443,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 +469,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) for the full details. ## Build File @@ -567,7 +567,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 +591,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 +600,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 +612,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 +623,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 +642,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/contributing/clean-room.md b/docs/docs/development/index.md similarity index 100% rename from docs/docs/development/contributing/clean-room.md rename to docs/docs/development/index.md diff --git a/docs/docs/development/local-toolchain/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx index cfcb39ee..464cf34d 100644 --- a/docs/docs/development/local-toolchain/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/local-toolchain/setup/docker.md b/docs/docs/development/local-toolchain/setup/docker.md index 767331e4..8d9f94bc 100644 --- a/docs/docs/development/local-toolchain/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/local-toolchain/setup/index.md b/docs/docs/development/local-toolchain/setup/index.md index 5c795fa2..71cc051e 100644 --- a/docs/docs/development/local-toolchain/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/local-toolchain/usb-logging.mdx b/docs/docs/development/local-toolchain/usb-logging.mdx index b7c3d233..2ae27ce5 100644 --- a/docs/docs/development/local-toolchain/usb-logging.mdx +++ b/docs/docs/development/local-toolchain/usb-logging.mdx @@ -69,9 +69,9 @@ sudo tio /dev/ttyACM0 On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Device Manager to figure out which COM port your controller is communicating on (listed under 'Ports (COM & LPT)') and specify that as the 'Serial line' in PuTTY. -![Controller COM port](../assets/usb-logging/com.jpg) +![Controller COM port](../../assets/usb-logging/com.jpg) -![PuTTY settings](../assets/usb-logging/putty.jpg) +![PuTTY settings](../../assets/usb-logging/putty.jpg) If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx index 44439e20..44521050 100644 --- a/docs/docs/development/new-behavior.mdx +++ b/docs/docs/development/new-behavior.mdx @@ -192,7 +192,7 @@ The dependencies required for any ZMK behavior are: - `device.h`: [Zephyr Device APIs](https://docs.zephyrproject.org/apidoc/latest/group__device__model.html) - `drivers/behavior.h`: ZMK Behavior Functions (e.g. [`locality`](#api-structure), `behavior_keymap_binding_pressed`, `behavior_keymap_binding_released`, `behavior_sensor_keymap_binding_triggered`) -- `logging/log.h`: [Zephyr Logging APIs](https://docs.zephyrproject.org/3.5.0/services/logging/index.html) (for more information on USB Logging in ZMK, see [USB Logging](usb-logging.mdx)). +- `logging/log.h`: [Zephyr Logging APIs](https://docs.zephyrproject.org/3.5.0/services/logging/index.html) (for more information on USB Logging in ZMK, see [USB Logging](local-toolchain/usb-logging.mdx)). - `zmk/behavior.h`: ZMK Behavior Information (e.g. parameters, position and timestamp of events) - `return` values: - `ZMK_BEHAVIOR_OPAQUE`: Used to terminate `on__binding_pressed` and `on__binding_released` functions that accept `(struct zmk_behavior_binding *binding, struct zmk_behavior_binding_event event)` as parameters @@ -432,8 +432,8 @@ 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. -- For hardware-based testing, see [USB Logging](usb-logging.mdx). +- See [Tests](local-toolchain/tests.md) for more information on how to create virtual test sets. +- For hardware-based testing, see [USB Logging](local-toolchain/usb-logging.mdx). ::: 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 e25bc72a..3027caf6 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 523f4971..88715f86 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..8b5b6da6 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/index.md). diff --git a/docs/docs/keymaps/behaviors/bluetooth.md b/docs/docs/keymaps/behaviors/bluetooth.md index 93d08428..960e238b 100644 --- a/docs/docs/keymaps/behaviors/bluetooth.md +++ b/docs/docs/keymaps/behaviors/bluetooth.md @@ -103,5 +103,5 @@ Please note there are five available Bluetooth profiles by default. If you need ::: :::note -If you clear bond of a paired profile, make sure you do the same thing on the peer device as well (typically achieved by _removing_ or _forgetting_ the bluetooth connection). Otherwise the peer will try to connect to your keyboard whenever it discovers it. But while the MAC address of both devices could remain the same, the security key no longer match: the peer device still possess the old key negotiated in the previous pairing procedure, but our keyboard firmware has deleted that key. So the connection will fail. If you [enabled USB logging](../../development/usb-logging.mdx), you might see a lot of failed connection attempts due to the reason of “Security failed”. +If you clear bond of a paired profile, make sure you do the same thing on the peer device as well (typically achieved by _removing_ or _forgetting_ the bluetooth connection). Otherwise the peer will try to connect to your keyboard whenever it discovers it. But while the MAC address of both devices could remain the same, the security key no longer match: the peer device still possess the old key negotiated in the previous pairing procedure, but our keyboard firmware has deleted that key. So the connection will fail. If you [enabled USB logging](../../development/local-toolchain/usb-logging.mdx), you might see a lot of failed connection attempts due to the reason of “Security failed”. ::: diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index a57a3d20..d09f510f 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -23,7 +23,7 @@ export const Uf2Tabs = (props) => ( ); :::tip -[USB logging](../development/usb-logging.mdx) can be very helpful for diagnosing issues with ZMK. However, when connected to USB your ZMK device will output to USB by default. To troubleshoot wireless connection issues using logging, you will need to [change the preferred output endpoint](../keymaps/behaviors/outputs.md). +[USB logging](../development/local-toolchain/usb-logging.mdx) can be very helpful for diagnosing issues with ZMK. However, when connected to USB your ZMK device will output to USB by default. To troubleshoot wireless connection issues using logging, you will need to [change the preferred output endpoint](../keymaps/behaviors/outputs.md). ::: ## Split Keyboard Halves Unable to Pair 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 ae26fd43..1d82767b 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", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index a053f4b8..1aad4a5f 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -115,10 +115,14 @@ module.exports = { ], }, { - Development: [ - "development/making-modules", - "development/studio-rpc-protocol", - "development/new-behavior", + type: "category", + label: "Development", + link: { + type: "doc", + id: "development/index", + }, + collapsed: true, + items: [ { type: "category", label: "Hardware Integration", @@ -133,15 +137,6 @@ module.exports = { "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", @@ -168,6 +163,9 @@ module.exports = { "development/local-toolchain/posix-board", ], }, + "development/studio-rpc-protocol", + "development/new-behavior", + "development/documentation", ], }, ], diff --git a/docs/static/_redirects b/docs/static/_redirects index 2113e0d9..866cb4ab 100644 --- a/docs/static/_redirects +++ b/docs/static/_redirects @@ -5,4 +5,15 @@ /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/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/usb-logging /docs/development/local-toolchain/usb-logging 301 +/docs/development/guides/new-behavior /docs/development/new-behavior 301 \ No newline at end of file From 5426abe64b699a7c1eabef84fd5387fd8156ca9e Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Fri, 30 Aug 2024 19:46:32 +0200 Subject: [PATCH 05/16] Added popup --- .../{index.md => contributing/clean-room.md} | 0 .../{ => contributing}/documentation.md | 0 docs/docs/development/new-behavior.mdx | 2 +- docs/docs/hardware.mdx | 2 +- docs/docusaurus.config.js | 2 +- docs/sidebars.js | 19 +++++----- docs/src/components/popup-manager.js | 35 +++++++++++++++++++ docs/src/components/popup.js | 35 +++++++++++++++++++ docs/src/css/popup.css | 33 +++++++++++++++++ docs/src/theme/Footer/index.js | 11 ++++++ 10 files changed, 127 insertions(+), 12 deletions(-) rename docs/docs/development/{index.md => contributing/clean-room.md} (100%) rename docs/docs/development/{ => contributing}/documentation.md (100%) create mode 100644 docs/src/components/popup-manager.js create mode 100644 docs/src/components/popup.js create mode 100644 docs/src/css/popup.css create mode 100644 docs/src/theme/Footer/index.js diff --git a/docs/docs/development/index.md b/docs/docs/development/contributing/clean-room.md similarity index 100% rename from docs/docs/development/index.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 100% rename from docs/docs/development/documentation.md rename to docs/docs/development/contributing/documentation.md diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx index 44521050..a93c3204 100644 --- a/docs/docs/development/new-behavior.mdx +++ b/docs/docs/development/new-behavior.mdx @@ -450,7 +450,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/hardware.mdx b/docs/docs/hardware.mdx index 8b5b6da6..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/hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/index.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/docusaurus.config.js b/docs/docusaurus.config.js index 1d82767b..012f63ac 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -81,7 +81,7 @@ module.exports = { }, { label: "Development", - to: "docs/development", + to: "docs/development/contributing/clean-room", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index 1aad4a5f..d6e03dcc 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -115,14 +115,7 @@ module.exports = { ], }, { - type: "category", - label: "Development", - link: { - type: "doc", - id: "development/index", - }, - collapsed: true, - items: [ + Development: [ { type: "category", label: "Hardware Integration", @@ -137,6 +130,15 @@ module.exports = { "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", @@ -165,7 +167,6 @@ module.exports = { }, "development/studio-rpc-protocol", "development/new-behavior", - "development/documentation", ], }, ], diff --git a/docs/src/components/popup-manager.js b/docs/src/components/popup-manager.js new file mode 100644 index 00000000..dd4a76c6 --- /dev/null +++ b/docs/src/components/popup-manager.js @@ -0,0 +1,35 @@ +import { useEffect, useState } from "react"; +import { useLocation } from "@docusaurus/router"; +import Popup from "./popup"; + +const PopupManager = () => { + const location = useLocation(); + const [showPopup, setShowPopup] = useState(false); + + const categoryPath = "/docs/development"; + const redirectPath = "/docs/development/contributing/clean-room"; + + useEffect(() => { + // Check if the current path is within the desired category + const isCategoryPage = location.pathname.startsWith(categoryPath); + + if (isCategoryPage) { + // Check localStorage to see if the popup has been shown before + const hasSeenPopup = localStorage.getItem("hasSeenCleanRoomWarningPopup"); + // If clean room is clicked directly no redirect necessary + if (window.location.pathname != redirectPath && !hasSeenPopup) { + setShowPopup(true); + localStorage.setItem("hasSeenCleanRoomWarningPopup", "true"); + } + } + }, [location.pathname]); + + const handleClose = () => { + window.location.href = redirectPath; + setShowPopup(false); + }; + + return showPopup ? : null; +}; + +export default PopupManager; diff --git a/docs/src/components/popup.js b/docs/src/components/popup.js new file mode 100644 index 00000000..4fb21ab6 --- /dev/null +++ b/docs/src/components/popup.js @@ -0,0 +1,35 @@ +import "../css/popup.css"; +import PropTypes from "prop-types"; + +const Popup = ({ onClose }) => { + return ( +
+
+

Clean Room Policy

+
+

+ Before reading this section, it is vital that you read + through our clean room policy. +

+
+
+ +
+
+
+ ); +}; + +export default Popup; + +Popup.propTypes = { + onClose: PropTypes.func.isRequired, +}; diff --git a/docs/src/css/popup.css b/docs/src/css/popup.css new file mode 100644 index 00000000..f80c3dd5 --- /dev/null +++ b/docs/src/css/popup.css @@ -0,0 +1,33 @@ +/* src/components/Popup.css */ +.popup-overlay { + position: fixed; + top: 0; + left: 0; + width: 100%; + height: 100%; + background: rgba(0, 0, 0, 0.5); + display: flex; + align-items: center; + justify-content: center; +} + +.popup-content { + border-left: 4px solid var(--ifm-color-danger-dark); /* Border width, style, and color */ + border-right: 4px solid var(--ifm-color-danger-dark); /* Border width, style, and color */ + justify-content: center; + background: var(--ifm-alert-background-color); + padding: 20px; + border-radius: 8px; + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1); + max-width: 700px; + width: 100%; +} + +.popup-content button { + margin-top: 10px; +} + +.centered-container { + display: flex; + justify-content: center; +} diff --git a/docs/src/theme/Footer/index.js b/docs/src/theme/Footer/index.js new file mode 100644 index 00000000..1db05429 --- /dev/null +++ b/docs/src/theme/Footer/index.js @@ -0,0 +1,11 @@ +import Footer from "@theme-original/Footer"; +import PopupManager from "../../components/popup-manager"; // Adjust path if necessary + +export default function FooterWrapper(props) { + return ( + <> + +