docs: Devcontainers-cli enhancement

.devcontainer/devcontainer.json

@@ -9,6 +9,7 @@
   "mounts": [
     "type=volume,source=zmk-root-user,target=/root",
     "type=volume,source=zmk-config,target=/workspaces/zmk-config",
+    "type=volume,source=zmk-module,target=/workspaces/zmk-module",
     "type=volume,source=zmk-zephyr,target=${containerWorkspaceFolder}/zephyr",
     "type=volume,source=zmk-zephyr-modules,target=${containerWorkspaceFolder}/modules",
     "type=volume,source=zmk-zephyr-tools,target=${containerWorkspaceFolder}/tools"

docs/docs/development/local-toolchain/build-flash.mdx

@@ -5,14 +5,22 @@ sidebar_label: Building and Flashing
 
 ## Building
 
-From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout:
+To build for your particular keyboard, the behavior varies slightly depending on
+if you are building for a keyboard with an onboard MCU, or one that uses an MCU
+board addon.
 
-```sh
-cd app
-```
+:::warning
+From here on the process for building and flashing varies based on the method
+you're using:
+
+- **[VS Code](setup/docker/vscode.md)/[Native](setup/native.mdx)**:
+  Execute the commands from within the `app/` subdirectory of the ZMK checkout.
+- **[Devcontainer CLI](setup/docker/cli.md)**:
+  Add `-s /absolute/path/to/zmk/app` to the `west` command.
 
-To build for your particular keyboard, the behavior varies slightly depending on if you are building for a keyboard with
-an onboard MCU, or one that uses an MCU board addon.
+If this is not done, you will encounter errors such as: `ERROR: source directory
+"." does not contain a CMakeLists.txt; is this really what you want to build?`
+:::
 
 ### Keyboard (Shield) + MCU Board
 
@@ -95,40 +103,26 @@ 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
-`-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.**
+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:
+For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder
+on Windows may look something like this:
 
 ```sh
-west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
+west build -b nice_nano -- -DSHIELD=kyria_left \
+  -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
 ```
 
 :::warning
-The above command must still be invoked from the `zmk/app` directory as noted above, rather than the config directory. Otherwise, you will encounter errors such as `ERROR: source directory "." does not contain a CMakeLists.txt; is this really what you want to build?`. Alternatively you can add the `-s /path/to/zmk/app` flag to your `west` command.
-:::
-
-:::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`
-by binding it to the full path of your config directory. If you have run the VSCode Remote Container before, it is likely that docker has created this
-volume automatically -- we need to delete the default volume before binding it to the correct path. Follow the following steps:
-
-1. Stop the container by exiting VSCode. You can verify no container is running via the command `docker ps`.
-1. Remove all the containers that are not running via the command `docker container prune`. We need to remove the ZMK container before we can delete the default `zmk-config` volume referenced by it. If you do not want to delete all the containers that are not running, you can find the id of the ZMK container and use `docker rm` to delete that one only.
-1. Remove the default volume via the command `docker volume rm zmk-config`.
-
-Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](customization.md) folder:
-
-```sh
-docker volume create --driver local -o o=bind -o type=none -o \
-    device="/full/path/to/your/zmk-config/" zmk-config
-```
-
-Now start VSCode and rebuild the container after being prompted. You should be able to see your zmk-config mounted to `/workspaces/zmk-config` inside the container. So you can build your custom firmware with `-DZMK_CONFIG="/workspaces/zmk-config/config"`.
-
 ## Flashing
 
 The above build commands generate a UF2 file in `build/zephyr` (or

docs/docs/development/local-toolchain/setup/docker/cli.md

@@ -0,0 +1,58 @@
+---
+title: Dev Container CLI
+sidebar_label: Dev Container CLI
+---
+
+### Installing Development Tools
+
+1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for
+   your operating system.
+2. Install the [Dev Container CLI](https://github.com/devcontainers/cli).
+
+### Initialize & Update Zephyr Workspace
+
+Open up your Terminal and make sure that the
+[Dev Container CLI](https://github.com/devcontainers/cli) is installed by
+running:
+
+```sh
+devcontainer --version
+```
+
+To be able to execute commands, the
+[Dev Container CLI](https://github.com/devcontainers/cli) has to know where the
+`devcontainer.json` is located. This can be done using the `--workspace-folder`
+option, which is available for all commands and will automatically look up the
+file relative to the path. Therefore, the container can be started by executing:
+
+```sh
+devcontainer up --workspace-folder "/absolute/path/to/zmk"
+```
+
+The first time you do this on your machine, it will pull down the Docker image
+from the registry and build the container. **Subsequent launches are much
+faster!**
+
+Once the command is finished, the development environment is available.
+Furthermore, the path is mounted under `/workspaces/zmk/`. It can then be used
+to initialize the application and update modules, including Zephyr.
+
+```sh
+devcontainer exec --workspace-folder "/absolute/path/to/zmk" \
+  west init -l "/workspaces/zmk/app"
+devcontainer exec --workspace-folder "/absolute/path/to/zmk" \
+  west update
+```
+
+:::tip
+This step pulls down quite a bit of tooling, be patient!
+:::
+
+:::info
+You must restart the container at this point. This can be done by using:
+
+- `docker container ps` to get the container id
+- `docker container stop <id>` to stop the container
+
+Your setup is complete once your container has been restarted.
+:::

docs/docs/development/local-toolchain/setup/docker/index.md

@@ -0,0 +1,77 @@
+---
+title: Docker
+sidebar_label: Docker
+---
+
+### Source Code
+
+First, you'll need to clone the ZMK source repository if you haven't already.
+Open a terminal and navigate to the folder you would like to place your `zmk`
+directory in, then run the following command:
+
+```sh
+git clone https://github.com/zmkfirmware/zmk.git
+```
+
+### Docker Setup
+
+Currently, there are two ways of building your local development environment:
+
+- [VS Code](vscode.md): \
+  This approach takes advantage of [VS Code](https://code.visualstudio.com/)’s
+  [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+  extension, allowing you to open the ZMK repository in a Docker container
+  directly within the editor. It is recommended for everyone who is familiar
+  with or already uses [VS Code](https://code.visualstudio.com/), since it
+  easily integrates with Docker and provides a seamless development experience.
+
+- [Dev Container CLI](cli.md): \
+  For users who prefer not to use [VS Code](https://code.visualstudio.com/), the
+  [Dev Container CLI](https://github.com/devcontainers/cli) provides a
+  command-line alternative for managing and running
+  [dev containers](https://containers.dev/), with similar functionality.
+
+### Additional Setup
+
+In case you have a `zmk-config` or want to build with additional modules, it is
+necessary to first make those available to the Docker container. This can be
+done by mounting them as volumes.
+
+But before you do so, first check that neither ZMK related containers nor the
+`zmk-config` and `zmk-module` volumes exist. This can be done with:
+
+```sh
+docker container ps                    # List active containers
+docker container stop "<container-id>" # Stop the container
+docker container rm   "<container-id>" # Remove the container
+
+docker volume ls                 # List volumes
+docker volume rm "<volume-name>" # Remove volume
+```
+
+:::note
+You can also use `docker container prune` to remove all containers if no others
+are running.
+:::
+
+#### `zmk-config`
+
+```sh
+docker volume create --driver local -o o=bind -o type=none \
+  -o device="/absolute/path/to/zmk-config/" zmk-config
+```
+
+#### Modules
+
+```sh
+docker volume create --driver local -o o=bind -o type=none -o \
+  device="/absolute/path/to/zmk-module/" zmk-module
+```
+
+:::tip
+Once this is done, you can refer to the `zmk-config` with
+`/workspace/zmk-config` and `/workspace/zmk-module` to the modules instead of
+using their full path like it is shown in the
+[build commands](../../build-flash.mdx), since these are the locations they were
+mounted to in the container.
+:::

docs/docs/development/local-toolchain/setup/docker/vscode.md

@@ -0,0 +1,59 @@
+---
+title: VS Code
+sidebar_label: VS Code
+---
+
+:::note
+This approach is documented for [VS Code](https://github.com/microsoft/vscode)
+not [Code OSS](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code).
+:::
+
+### Installing Development Tools
+
+1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for
+   your operating system.
+2. Install [VS Code](https://code.visualstudio.com/).
+3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+
+### Initialize & Update Zephyr Workspace
+
+Open the `zmk` checkout directory in VS Code. The repository includes a
+configuration for containerized development. Therefore, an alert will pop up:
+
+![VS Code Dev Container Configuration Alert](../../../../assets/dev-setup/vscode_devcontainer.png)
+
+Click `Reopen in Container` 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 the following keys based on your operating system and
+selecting `Remote: Show Remote Menu`:
+
+- **Windows/Linux**: `Ctrl + Shift + P`
+- **MacOs**: `Cmd + Shift + P`
+
+The first time you do this on your machine, it will pull down the Docker image
+from the registry and build the container. **Subsequent launches are much
+faster!**
+
+:::caution
+The following step and any future [build commands](../../build-flash.mdx) must
+be executed from the VS Code terminal _inside_ the container.
+:::
+
+Initialize the application and update modules, including Zephyr:
+
+```sh
+west init -l app/
+west update
+```
+
+:::tip
+This step pulls down quite a bit of tooling, be patient!
+:::
+
+:::info
+You must restart the container at this point. The easiest way to do this is to
+close the VS Code window, verify that the container has stopped in the Docker
+Dashboard, and reopen the container with VS Code.
+
+Your setup is complete once your container has restarted.
+:::

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](docker.md): \
+- [Docker](docker/index.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](native.mdx):\
+- [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](docker.md) instructions or [native](native.mdx) instructions to continue setup.
+Please see the [Docker](docker/index.md) instructions or [native](native.mdx) instructions to continue setup.

docs/sidebars.js

@@ -155,7 +155,19 @@ module.exports = {
               },
               collapsed: true,
               items: [
-                "development/local-toolchain/setup/docker",
+                {
+                  type: "category",
+                  label: "Docker",
+                  link: {
+                    type: "doc",
+                    id: "development/local-toolchain/setup/docker/index",
+                  },
+                  collapsed: true,
+                  items: [
+                    "development/local-toolchain/setup/docker/vscode",
+                    "development/local-toolchain/setup/docker/cli",
+                  ],
+                },
                 "development/local-toolchain/setup/native",
               ],
             },