diff --git a/docs/docs/development/setup/docker-vscode.md b/docs/docs/development/setup/docker-vscode.md index aa8ed630..758522bf 100644 --- a/docs/docs/development/setup/docker-vscode.md +++ b/docs/docs/development/setup/docker-vscode.md @@ -10,7 +10,7 @@ The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You m :::note Windows Users Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s. -This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code as well. +This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code. Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`. ::: @@ -21,6 +21,6 @@ This setup leverages the same [image which is used by the GitHub action](https:/ 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) -:::info -Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk) -::: +## ZMK Sources Setup + +Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk). diff --git a/docs/docs/development/setup/getting-started.md b/docs/docs/development/setup/getting-started.md new file mode 100644 index 00000000..b432cfbc --- /dev/null +++ b/docs/docs/development/setup/getting-started.md @@ -0,0 +1,24 @@ +--- +title: Getting Started +sidebar_label: Getting Started +--- + +## Environment Setup + +There are two ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. + +Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. + +:::danger +The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. +::: + +## Standard Conventions + +Throughout this documentation you will see commands like + +``` +sudo apt update +``` + +These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows). diff --git a/docs/docs/development/setup/native.md b/docs/docs/development/setup/native.md index 18b9880e..42eaeb86 100644 --- a/docs/docs/development/setup/native.md +++ b/docs/docs/development/setup/native.md @@ -430,6 +430,6 @@ cat ~/.zephyrrc >> ~/.zshrc -:::info -Once the above is setup you're ready to setup the ZMK sources as defined [here](/docs/development/setup/zmk) -::: +## ZMK Sources Setup + +Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk). diff --git a/docs/docs/development/setup/setup.md b/docs/docs/development/setup/setup.md deleted file mode 100644 index 4c23d9a2..00000000 --- a/docs/docs/development/setup/setup.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Getting Started -sidebar_label: Getting Started ---- - -## Environment Setup - -There are 2 ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially. - -Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup. - -:::danger -The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU. -::: - -## ZMK Sources Setup - -Once you've setup either the Docker environment or native environment you will need to setup the ZMK sources. Please see the [ZMK Sources](/docs/development/setup/zmk) section once you've setup your chosen environment. - -## Standard Conventions - -Throughout this documentation you will see commands like - -``` -sudo apt update -``` - -These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows). diff --git a/docs/docs/development/setup/zmk.md b/docs/docs/development/setup/zmk.md index aa34248e..3965d534 100644 --- a/docs/docs/development/setup/zmk.md +++ b/docs/docs/development/setup/zmk.md @@ -11,18 +11,14 @@ groupId="operating-systems" defaultValue="docker" values={[ {label: 'VS Code & Docker', value: 'docker'}, -{label: 'Debian/Ubuntu', value: 'debian'}, -{label: 'macOS', value: 'mac'}, -{label: 'Windows', value: 'win'}, -{label: 'Raspberry OS', value: 'raspberryos'}, -{label: 'Fedora', value: 'fedora'}, +{label: 'Native', value: 'native'}, ] }>{props.children}); :::caution Windows Users If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue. -If you're using the WSL2 native filesystem the sources should go under `~/` to avoid potential permissions issues. +If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues. ::: ### Source Code @@ -58,35 +54,7 @@ All subsequent steps must be performed from the VS Code terminal _inside_ the co - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - + ```sh cd zmk @@ -101,9 +69,9 @@ cd zmk west init -l app/ ``` -:::caution Command Not Found? (Native OS) +:::caution Command Not Found? If you encounter errors like `command not found: west` then your `PATH` environment variable is likely -missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) +missing the Python 3 user packages directory. See the [Native setup](native/) section again for links to how to do this ::: @@ -125,6 +93,10 @@ west zephyr-export #### Install Zephyr Python Dependencies +:::note +This only need to be run when using the Native setup. +::: + ```sh pip3 install --user -r zephyr/scripts/requirements-base.txt ``` diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c5dec773..d8ab68b5 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -48,7 +48,7 @@ module.exports = { }, { label: "Development", - to: "docs/development/setup/setup", + to: "docs/development/setup/getting-started", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index 0df9f1ca..abf009db 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -48,7 +48,7 @@ module.exports = { label: "Setup", collapsed: false, items: [ - "development/setup/setup", + "development/setup/getting-started", "development/setup/docker-vscode", "development/setup/native", "development/setup/zmk",