summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorErovia <erovia@users.noreply.github.com>2020-03-22 19:48:30 +0100
committerskullydazed <skullydazed@users.noreply.github.com>2020-04-08 09:31:14 -0700
commit5cfc3ce02e3c8007ac42e8089ecc895771bb3bfb (patch)
treecd57c376585c927e353190a785810b68ad9f9594 /docs
parent724f20ed32758b0c5d91ad4b7ba4a9348e152eeb (diff)
Rebase on master, hide some other subcommands
The list of hidden subcommands were approved by @skullydazed ;) Currently hidden if 'user.developer' is not True: - cformat - docs - kle2json - pyformat - pytest
Diffstat (limited to 'docs')
-rw-r--r--docs/cli.md250
-rw-r--r--docs/cli_commands.md10
-rw-r--r--docs/cli_development.md12
3 files changed, 21 insertions, 251 deletions
diff --git a/docs/cli.md b/docs/cli.md
index 625ac4fb70..760fe1cdb5 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -37,253 +37,3 @@ We are looking for people to create and maintain a `qmk` package for more operat
* Document why in a comment when you do deviate
* Install using a virtualenv
* Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`.
-
-# Local CLI
-
-If you do not want to use the global CLI there is a local CLI bundled with `qmk_firmware`. You can find it in `qmk_firmware/bin/qmk`. You can run the `qmk` command from any directory and it will always operate on that copy of `qmk_firmware`.
-
-**Example**:
-
-```
-$ ~/qmk_firmware/bin/qmk hello
-Ψ Hello, World!
-```
-
-## Local CLI Limitations
-
-There are some limitations to the local CLI compared to the global CLI:
-
-* The local CLI does not support `qmk setup` or `qmk clone`
-* The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned.
-* The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict
-
-# CLI Commands
-
-## `qmk cformat`
-
-*dev mode*
-
-This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files.
-
-**Usage**:
-
-```
-qmk cformat [file1] [file2] [...] [fileN]
-```
-
-## `qmk compile`
-
-This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
-
-**Usage for Configurator Exports**:
-
-```
-qmk compile <configuratorExport.json>
-```
-
-**Usage for Keymaps**:
-
-```
-qmk compile -kb <keyboard_name> -km <keymap_name>
-```
-
-**Usage in Keyboard Directory**:
-
-Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>`
-```
-qmk compile
-```
-
-**Example**:
-```
-$ qmk config compile.keymap=default
-$ cd ~/qmk_firmware/keyboards/planck/rev6
-$ qmk compile
-Ψ Compiling keymap with make planck/rev6:default
-...
-```
-or with optional keymap argument
-
-```
-$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
-$ qmk compile -km 66_iso
-Ψ Compiling keymap with make clueboard/66/rev4:66_iso
-...
-```
-or in keymap directory
-
-```
-$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
-$ qmk compile
-Ψ Compiling keymap with make make gh60/satan:colemak
-...
-```
-
-**Usage in Layout Directory**:
-
-Must be under `qmk_firmware/layouts/`, and in a keymap folder.
-```
-qmk compile -kb <keyboard_name>
-```
-
-**Example**:
-```
-$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
-$ qmk compile -kb dz60
-Ψ Compiling keymap with make dz60:mechmerlin-ansi
-...
-```
-
-## `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 <https://docs.qmk.fm/#/flashing>
-for more details of the available bootloaders.
-
-**Usage for Configurator Exports**:
-
-```
-qmk flash <configuratorExport.json> -bl <bootloader>
-```
-
-**Usage for Keymaps**:
-
-```
-qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
-```
-
-**Listing the Bootloaders**
-
-```
-qmk flash -b
-```
-
-## `qmk config`
-
-This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
-
-**Usage**:
-
-```
-qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
-```
-
-## `qmk docs`
-
-This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
-
-**Usage**:
-
-```
-qmk docs [-p PORT]
-```
-
-## `qmk doctor`
-
-This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to.
-
-**Usage**:
-
-```
-qmk doctor [-y] [-n]
-```
-
-**Examples**:
-
-Check your environment for problems and prompt to fix them:
-
- qmk doctor
-
-Check your environment and automatically fix any problems found:
-
- qmk doctor -y
-
-Check your environment and report problems only:
-
- qmk doctor -n
-
-## `qmk json-keymap`
-
-Creates a keymap.c from a QMK Configurator export.
-
-**Usage**:
-
-```
-qmk json-keymap [-o OUTPUT] filename
-```
-
-## `qmk kle2json`
-
-This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
-
-**Usage**:
-
-```
-qmk kle2json [-f] <filename>
-```
-
-**Examples**:
-
-```
-$ qmk kle2json kle.txt
-☒ File info.json already exists, use -f or --force to overwrite.
-```
-
-```
-$ qmk kle2json -f kle.txt -f
-Ψ Wrote out to info.json
-```
-
-## `qmk list-keyboards`
-
-This command lists all the keyboards currently defined in `qmk_firmware`
-
-**Usage**:
-
-```
-qmk list-keyboards
-```
-
-## `qmk list-keymaps`
-
-This command lists all the keymaps for a specified keyboard (and revision).
-
-**Usage**:
-
-```
-qmk list-keymaps -kb planck/ez
-```
-
-## `qmk new-keymap`
-
-This command creates a new keymap based on a keyboard's existing default keymap.
-
-**Usage**:
-
-```
-qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
-```
-
-## `qmk pyformat`
-
-*dev mode*
-
-This command formats python code in `qmk_firmware`.
-
-**Usage**:
-
-```
-qmk pyformat
-```
-
-## `qmk pytest`
-
-*dev mode*
-
-This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
-
-**Usage**:
-
-```
-qmk pytest
-```
diff --git a/docs/cli_commands.md b/docs/cli_commands.md
index eb5362bd29..570f841bc8 100644
--- a/docs/cli_commands.md
+++ b/docs/cli_commands.md
@@ -4,6 +4,8 @@
## `qmk cformat`
+*(dev mode)*
+
This command formats C code using clang-format.
Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
@@ -138,6 +140,8 @@ qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
## `qmk docs`
+*(dev mode)*
+
This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
**Usage**:
@@ -182,6 +186,8 @@ qmk json2c [-o OUTPUT] filename
## `qmk kle2json`
+*(dev mode)*
+
This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
**Usage**:
@@ -234,6 +240,8 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
## `qmk pyformat`
+*(dev mode)*
+
This command formats python code in `qmk_firmware`.
**Usage**:
@@ -244,6 +252,8 @@ qmk pyformat
## `qmk pytest`
+*(dev mode)*
+
This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
**Usage**:
diff --git a/docs/cli_development.md b/docs/cli_development.md
index e41afc42f4..2a967de4ab 100644
--- a/docs/cli_development.md
+++ b/docs/cli_development.md
@@ -6,7 +6,17 @@ This document has useful information for developers wishing to write new `qmk` s
The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None.
-*Tip*: Enable dev mode by `qmk config user.developer=True`
+## Developer mode:
+
+If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode:
+
+`qmk config user.developer=True`
+
+This will allow you to see all available subcommands.
+**Note:** You will have to install additional requirements:
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
# Subcommands