Deprecate `qmk generate-compilation-database`. (#25237)

3 files changed, 34 insertions, 29 deletions

diff --git a/docs/ChangeLog/20250525/pr25237.md b/docs/ChangeLog/20250525/pr25237.md
new file mode 100644
index 0000000000..ca09e93ebc
--- /dev/null
+++ b/docs/ChangeLog/20250525/pr25237.md
@@ -0,0 +1,3 @@
+# Deprecation of `qmk generate-compilation-database`
+
+This command has been deprecated as it cannot take into account configurables such as [converters](/feature_converters) or environment variables normally specified on the command line; please use the `--compiledb` flag with `qmk compile` instead.
diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index d17b0eda23..c6a7ffe191 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -17,7 +17,7 @@ qmk compile [-c] <configuratorExport.json>
 **Usage for Keymaps**:
 
 ```
-qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name>
+qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] [--compiledb] -kb <keyboard_name> -km <keymap_name>
 ```
 
 **Usage in Keyboard Directory**:
@@ -84,6 +84,25 @@ The `num_jobs` argument determines the maximum number of jobs that can be used.
 qmk compile -j 0 -kb <keyboard_name>
 ```
 
+**Compilation Database**:
+
+Creates a `compile_commands.json` file.
+
+Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! Compiling using this argument can create this for you.
+
+**Example:**
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk compile --compiledb
+Ψ Making clean
+Ψ Gathering build instructions from make ........
+Ψ Found 63 compile commands
+Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
+Ψ Compiling keymap with make ........
+... build log continues ...
+```
+
 ## `qmk flash`
 
 This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing) guide for more details of the available bootloaders.
@@ -694,33 +713,6 @@ qmk format-c
 qmk format-c -b branch_name
 ```
 
-## `qmk generate-compilation-database`
-
-**Usage**:
-
-```
-qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
-```
-
-Creates a `compile_commands.json` file.
-
-Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! The qmk tool can build this for you.
-
-This command needs to know which keyboard and keymap to build. It uses the same configuration options as the `qmk compile` command: arguments, current directory, and config files.
-
-**Example:**
-
-```
-$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
-$ qmk generate-compilation-database
-Ψ Making clean
-Ψ Gathering build instructions from make -n gh60/satan:colemak
-Ψ Found 50 compile commands
-Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
-```
-
-Now open your dev environment and live a squiggly-free life.
-
 ## `qmk docs`
 
 This command starts a local HTTP server which you can use for browsing or improving the docs, and provides live reload capability whilst editing. Default port is 8936.
@@ -885,3 +877,13 @@ Run single test:
 ```
 qmk test-c --test basic
 ```
+
+## `qmk generate-compilation-database`
+
+**Usage**:
+
+```
+qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
+```
+
+This command has been deprecated as it cannot take into account configurables such as [converters](/feature_converters) or environment variables normally specified on the command line; please use the `--compiledb` flag with `qmk compile` instead.
diff --git a/docs/other_vscode.md b/docs/other_vscode.md
index ab2b23e96b..0b39746a6e 100644
--- a/docs/other_vscode.md
+++ b/docs/other_vscode.md
@@ -112,7 +112,7 @@ Restart once you've installed any extensions.
 
 Using the [standard `compile_commands.json` database](https://clang.llvm.org/docs/JSONCompilationDatabase.html), we can get the VS code _clangd_ extension to use the correct includes and defines used for your keyboard and keymap.
 
-1. Run `qmk generate-compilation-database -kb <keyboard> -km <keymap>` to generate the `compile_commands.json`.
+1. Run `qmk compile -kb <keyboard> -km <keymap> --compiledb` to generate the `compile_commands.json`.
 1. Inside VS code, press <kbd><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd> (macOS: <kbd><kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd>) to open the command palette.
 1. Start typing `clangd: Download Language Server` and select it when it appears. Note that this only needs to be done once on clangd extension installation, if it didn't already ask to do so.
 1. Inside VS code, press <kbd><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd> (macOS: <kbd><kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></kbd>) to open the command palette.