From 0955ffef65c1935b25028d84b512654a2ea67d66 Mon Sep 17 00:00:00 2001
From: Joel Spadin <joelspadin@gmail.com>
Date: Sat, 19 Sep 2020 16:32:24 -0500
Subject: [PATCH] docs: Add docs for setting up vscode

Added a docs page with tips for setting up VS Code's code completion to work
in ZMK's source files. Info for other IDEs can be added here later as needed.
---
 docs/docs/development/ide-integration.md | 139 +++++++++++++++++++++++
 docs/sidebars.js                         |   1 +
 2 files changed, 140 insertions(+)
 create mode 100644 docs/docs/development/ide-integration.md

diff --git a/docs/docs/development/ide-integration.md b/docs/docs/development/ide-integration.md
new file mode 100644
index 00000000..20ab6926
--- /dev/null
+++ b/docs/docs/development/ide-integration.md
@@ -0,0 +1,139 @@
+---
+title: IDE Integration
+sidebar_label: IDE Integration
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+export const OsTabs = (props) => (<Tabs
+groupId="operating-systems"
+defaultValue="debian"
+values={[
+{label: 'Debian/Ubuntu', value: 'debian'},
+{label: 'Windows', value: 'win'},
+{label: 'macOS', value: 'mac'},
+{label: 'Raspberry OS', value: 'raspberryos'},
+{label: 'Fedora', value: 'fedora'},
+{label: 'VS Code & Docker', value: 'docker'},
+]
+}>{props.children}</Tabs>);
+
+## Visual Studio Code
+
+Visual Studio Code needs to know some things about the project such as include
+paths and compiler paths before features such as code completion, go to definition,
+and graying out disabled code blocks will work. Fortunately, CMake can generate
+that configuration for us automatically.
+
+### Create a Compilation Database
+
+To configure `west` to tell CMake to generate a compilation database, open a
+terminal to the ZMK repository and run the following command:
+
+```sh
+west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+Every [build](build-flash#building) will now update the database. You will
+need to build once to create the database before code completion will work.
+We'll tell Visual Studio Code where to find the database in the next step.
+
+:::note
+If you have set any other CMake arguments such as the path to your zmk-config, the
+above command will overwrite them. You should instead provide the flag to export
+compile commands and all other arguments surrounded by quotes. For example:
+
+```sh
+west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DZMK_CONFIG=/path/to/zmk-config/config"
+```
+
+:::
+
+### Create a C/C++ Configuration
+
+Install the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools),
+then run **F1 > C/C++: Edit Configurations (UI)**. It should automatically create
+a new configuration for you, but if the text box under **Configuration name** is empty,
+click **Add Configuration**, enter a name, and click **OK**.
+
+Change these options:
+
+| Option                                | Value                                                |
+| ------------------------------------- | ---------------------------------------------------- |
+| Compiler path                         | Path to your toolchain's GCC binary (see below)      |
+| IntelliSense mode                     | gcc-arm                                              |
+| Advanced Settings > Compiler commands | `${workspaceFolder}/app/build/compile_commands.json` |
+
+<OsTabs>
+<TabItem value="debian">
+
+Open VS Code's integrated terminal and run the following commands. It will print
+your compiler path.
+
+```sh
+source zephyr/zephyr-env.sh
+echo ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
+```
+
+:::note
+You will need to update this path any time you switch to a new version of the Zephyr SDK.
+:::
+
+</TabItem>
+<TabItem value="win">
+
+Your compiler path is
+
+```
+${env:GNUARMEMB_TOOLCHAIN_PATH}/bin/arm-none-eabi-gcc.exe
+```
+
+This assumes `GNUARMEMB_TOOLCHAIN_PATH` is set in your system or user environment variables.
+If not, you will need to list the full path instead of using the `${env}` placeholder.
+
+</TabItem>
+<TabItem value="mac">
+
+Open VS Code's integrated terminal and run the following command. It will print
+your compiler path.
+
+```sh
+echo ${GNUARMEMB_TOOLCHAIN_PATH}/bin/arm-none-eabi-gcc
+```
+
+</TabItem>
+<TabItem value="raspberryos">
+
+Your compiler path is
+
+```
+/usr/bin/arm-none-eabi-gcc
+```
+
+</TabItem>
+<TabItem value="fedora">
+
+Open VS Code's integrated terminal and run the following commands. It will print
+your compiler path.
+
+```sh
+source zephyr/zephyr-env.sh
+echo ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
+```
+
+:::note
+You will need to update this path any time you switch to a new version of the Zephyr SDK.
+:::
+
+</TabItem>
+<TabItem value="docker">
+
+Your compiler path is
+
+```
+${env:ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
+```
+
+</TabItem>
+</OsTabs>
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 98ffb19e..e98b3f81 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -49,6 +49,7 @@ module.exports = {
       "development/posix-board",
       "development/tests",
       "development/usb-logging",
+      "development/ide-integration",
       {
         type: "category",
         label: "Guides",