From 86f6405574d75cdc69c32829cb523aa1538ecd77 Mon Sep 17 00:00:00 2001 From: skullY Date: Tue, 25 Feb 2020 09:17:24 -0800 Subject: More sidebar organization --- docs/_summary.md | 155 ++++++++++++++++++++----------------- docs/cli_configuration.md | 121 ----------------------------- docs/cli_dev_configuration.md | 121 +++++++++++++++++++++++++++++ docs/getting_started_github.md | 65 ---------------- docs/newbs_learn_more_resources.md | 12 ++- 5 files changed, 209 insertions(+), 265 deletions(-) delete mode 100644 docs/cli_configuration.md create mode 100644 docs/cli_dev_configuration.md delete mode 100644 docs/getting_started_github.md diff --git a/docs/_summary.md b/docs/_summary.md index dee8a31984..994d585572 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -1,17 +1,20 @@ * Complete Newbs Guide * [Introduction](newbs.md) - * [Getting Started](newbs_getting_started.md) + * [Setup](newbs_getting_started.md) * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) * [Getting Help](getting_started_getting_help.md) + * Other Topics + * [Learning Resources](newbs_learn_more_resources.md) + * [Using Eclipse with QMK](other_eclipse.md) + * [Using VSCode with QMK](other_vscode.md) * FAQs * [General FAQ](faq_general.md) * [Build/Compile QMK](faq_build.md) * [Debugging/Troubleshooting QMK](faq_debug.md) * [Keymap](faq_keymap.md) - * [Driver Installation with Zadig](driver_installation_zadig.md) * Configurator * [Overview](newbs_building_firmware_configurator.md) @@ -20,74 +23,80 @@ * [Overview](api_overview.md) * [API Documentation](api_docs.md) +* CLI + * [Overview](cli.md) + * [Configuration](cli_configuration.md) + * [Commands](cli_commands.md) + * Using QMK * Guides - * [ARM Debugging Guide](arm_debugging.md) - * [Best Git Practices](newbs_git_best_practices.md) - * [Contributing to QMK](contributing.md) * [Customizing Functionality](custom_quantum_functions.md) - * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md) - * [Flashing Firmware](flashing.md) - * [Github Best Practices](getting_started_github.md) - * [Hand Wiring Guide](hand_wire.md) - * [ISP Flashing Guide](isp_flashing_guide.md) + * [Driver Installation with Zadig](driver_installation_zadig.md) * [Keymap Overview](keymap.md) - * [Learning Resources](newbs_learn_more_resources.md) - * [QMK CLI](cli.md) * [Vagrant Guide](getting_started_vagrant.md) + * Flashing + * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md) + * [Flashing Firmware](flashing.md) + * Git Best Practices + * [Introduction](newbs_git_best_practices.md) + * [Your Fork](newbs_git_using_your_master_branch.md) + * [Merge Conflicts](newbs_git_resolving_merge_conflicts.md) + * [Fixing Your Branch](newbs_git_resynchronize_a_branch.md) + * Keyboard Building + * [Hand Wiring Guide](hand_wire.md) + * [ISP Flashing Guide](isp_flashing_guide.md) - * QMK Features - * Keycodes - * [Full List](keycodes.md) - * [Basic Keycodes](keycodes_basic.md) - * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) - * [Quantum Keycodes](quantum_keycodes.md) - * [Advanced Keycodes](feature_advanced_keycodes.md) + * Simple Keycodes + * [Full List](keycodes.md) + * [Basic Keycodes](keycodes_basic.md) + * [Advanced Keycodes](feature_advanced_keycodes.md) + * [Quantum Keycodes](quantum_keycodes.md) - * Software Features - * [Auto Shift](feature_auto_shift.md) - * [Combos](feature_combo.md) - * [Command](feature_command.md) - * [Debounce API](feature_debounce_type.md) - * [Dynamic Macros](feature_dynamic_macros.md) - * [Grave Escape](feature_grave_esc.md) - * [Key Lock](feature_key_lock.md) - * [Leader Key](feature_leader_key.md) - * [Macros](feature_macros.md) - * [Mouse Keys](feature_mouse_keys.md) - * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - * [Pointing Device](feature_pointing_device.md) - * [Space Cadet](feature_space_cadet.md) - * [Swap Hands](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Terminal](feature_terminal.md) - * [Unicode](feature_unicode.md) - * [Userspace](feature_userspace.md) + * Advanced Keycodes + * [Auto Shift](feature_auto_shift.md) + * [Command](feature_command.md) + * [Dynamic Macros](feature_dynamic_macros.md) + * [Grave Escape](feature_grave_esc.md) + * [Leader Key](feature_leader_key.md) + * [Macros](feature_macros.md) + * [Mouse Keys](feature_mouse_keys.md) + * [Space Cadet Shift](feature_space_cadet.md) + * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) - * Hardware Features - * [Audio](feature_audio.md) - * [Backlight](feature_backlight.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) - * [Custom Matrix](custom_matrix.md) - * [DIP Switch](feature_dip_switch.md) - * [Encoders](feature_encoders.md) - * [Haptic Feedback](feature_haptic_feedback.md) + * Software Features + * [Combos](feature_combo.md) + * [Debounce API](feature_debounce_type.md) + * [Key Lock](feature_key_lock.md) + * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) + * [Pointing Device](feature_pointing_device.md) + * [Swap Hands](feature_swap_hands.md) + * [Tap Dance](feature_tap_dance.md) + * [Terminal](feature_terminal.md) + * [Unicode](feature_unicode.md) + * [Userspace](feature_userspace.md) + + * Hardware Features + * Displays * [HD44780 LCD Controller](feature_hd44780.md) - * [LED Matrix](feature_led_matrix.md) * [OLED Driver](feature_oled_driver.md) - * [Proton C Conversion](proton_c_conversion.md) - * [PS/2 Mouse](feature_ps2_mouse.md) + * Lighting + * [Backlight](feature_backlight.md) + * [LED Matrix](feature_led_matrix.md) * [RGB Lighting](feature_rgblight.md) * [RGB Matrix](feature_rgb_matrix.md) - * [Split Keyboard](feature_split_keyboard.md) - * [Stenography](feature_stenography.md) - * [Thermal Printer](feature_thermal_printer.md) - * [Velocikey](feature_velocikey.md) - - * Other Topics - * [Using Eclipse with QMK](other_eclipse.md) - * [Using VSCode with QMK](other_vscode.md) + * [Audio](feature_audio.md) + * [Bluetooth](feature_bluetooth.md) + * [Bootmagic](feature_bootmagic.md) + * [Custom Matrix](custom_matrix.md) + * [DIP Switch](feature_dip_switch.md) + * [Encoders](feature_encoders.md) + * [Haptic Feedback](feature_haptic_feedback.md) + * [Proton C Conversion](proton_c_conversion.md) + * [PS/2 Mouse](feature_ps2_mouse.md) + * [Split Keyboard](feature_split_keyboard.md) + * [Stenography](feature_stenography.md) + * [Thermal Printer](feature_thermal_printer.md) + * [Velocikey](feature_velocikey.md) * Developing QMK * Breaking Changes @@ -96,19 +105,8 @@ * History * [2019 Aug 30](ChangeLog/20190830.md) - * QMK Reference - * [Translating the QMK Docs](translating.md) - * [Config Options](config_options.md) - * [Make Documentation](getting_started_make_guide.md) - * [Documentation Best Practices](documentation_best_practices.md) - * [Documentation Templates](documentation_templates.md) - * [Glossary](reference_glossary.md) - * [Community Layouts](feature_layouts.md) - * [Unit Testing](unit_testing.md) - * [Useful Functions](ref_functions.md) - * [info.json Format](reference_info_json.md) - * C Development + * [ARM Debugging Guide](arm_debugging.md) * [AVR Processors](hardware_avr.md) * [Coding Conventions](coding_conventions_c.md) * [Compatible Microcontrollers](compatible_microcontrollers.md) @@ -122,14 +120,27 @@ * Python Development * [Coding Conventions](coding_conventions_python.md) - * [QMK CLI Config](cli_configuration.md) - * [Python CLI Development](cli_development.md) + * [QMK CLI Development](cli_development.md) + * [QMK CLI Config](cli_dev_configuration.md) * Configurator Development * QMK API * [Development Environment](api_development_environment.md) * [Architecture Overview](api_development_overview.md) + * QMK Reference + * [Contributing to QMK](contributing.md) + * [Translating the QMK Docs](translating.md) + * [Config Options](config_options.md) + * [Make Documentation](getting_started_make_guide.md) + * [Documentation Best Practices](documentation_best_practices.md) + * [Documentation Templates](documentation_templates.md) + * [Glossary](reference_glossary.md) + * [Community Layouts](feature_layouts.md) + * [Unit Testing](unit_testing.md) + * [Useful Functions](ref_functions.md) + * [info.json Format](reference_info_json.md) + * For a Deeper Understanding * [How Keyboards Work](how_keyboards_work.md) * [Understanding QMK](understanding_qmk.md) diff --git a/docs/cli_configuration.md b/docs/cli_configuration.md deleted file mode 100644 index ad9ff291c8..0000000000 --- a/docs/cli_configuration.md +++ /dev/null @@ -1,121 +0,0 @@ -# QMK CLI Configuration - -This document explains how `qmk config` works. - -# Introduction - -Configuration for QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set. - -## Simple Example - -As an example let's look at the command `qmk compile --keyboard clueboard/66/rev4 --keymap default`. - -There are two command line arguments that could be read from configuration instead: - -* `compile.keyboard` -* `compile.keymap` - -Let's set these now: - -``` -$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default -compile.keyboard: None -> clueboard/66/rev4 -compile.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -Now I can run `qmk compile` without specifying my keyboard and keymap each time. - -## Setting User Defaults - -Sometimes you want to share a setting between multiple commands. For example, multiple commands take the argument `--keyboard`. Rather than setting this value for every command you can set a user value which will be used by any command that takes that argument. - -Example: - -``` -$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default -user.keyboard: None -> clueboard/66/rev4 -user.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# CLI Documentation (`qmk config`) - -The `qmk config` command is used to interact with the underlying configuration. When run with no argument it shows the current configuration. When arguments are supplied they are assumed to be configuration tokens, which are strings containing no spaces with the following form: - - [.][=] - -## Setting Configuration Values - -You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `
.` form. - -Example: - -``` -$ qmk config default.keymap=default -default.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## Reading Configuration Values - -You can read configuration values for the entire configuration, a single key, or for an entire section. You can also specify multiple keys to display more than one value. - -### Entire Configuration Example - - qmk config - -### Whole Section Example - - qmk config compile - -### Single Key Example - - qmk config compile.keyboard - -### Multiple Keys Example - - qmk config user compile.keyboard compile.keymap - -## Deleting Configuration Values - -You can delete a configuration value by setting it to the special string `None`. - -Example: - -``` -$ qmk config default.keymap=None -default.keymap: default -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## Multiple Operations - -You can combine multiple read and write operations into a single command. They will be executed and displayed in order: - -``` -$ qmk config compile default.keymap=default compile.keymap=None -compile.keymap=skully -compile.keyboard=clueboard/66_hotswap/gen1 -default.keymap: None -> default -compile.keymap: skully -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# User Configuration Options - -| Key | Default Value | Description | -|-----|---------------|-------------| -| user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | -| user.keymap | None | The keymap name (Example: `default`) | -| user.name | None | The user's github username. | - -# All Configuration Options - -| Key | Default Value | Description | -|-----|---------------|-------------| -| compile.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | -| compile.keymap | None | The keymap name (Example: `default`) | -| hello.name | None | The name to greet when run. | -| new_keyboard.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | -| new_keyboard.keymap | None | The keymap name (Example: `default`) | diff --git a/docs/cli_dev_configuration.md b/docs/cli_dev_configuration.md new file mode 100644 index 0000000000..1196ab669d --- /dev/null +++ b/docs/cli_dev_configuration.md @@ -0,0 +1,121 @@ +# QMK CLI Configuration + +This document explains how `qmk config` works. + +# Introduction + +Configuration for the QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set. + +## Simple Example + +As an example let's look at the command `qmk compile --keyboard clueboard/66/rev4 --keymap default`. + +There are two command line arguments that could be read from configuration instead: + +* `compile.keyboard` +* `compile.keymap` + +Let's set these now: + +``` +$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default +compile.keyboard: None -> clueboard/66/rev4 +compile.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +Now I can run `qmk compile` without specifying my keyboard and keymap each time. + +## Setting User Defaults + +Sometimes you want to share a setting between multiple commands. For example, multiple commands take the argument `--keyboard`. Rather than setting this value for every command you can set a user value which will be used by any command that takes that argument. + +Example: + +``` +$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default +user.keyboard: None -> clueboard/66/rev4 +user.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# CLI Documentation (`qmk config`) + +The `qmk config` command is used to interact with the underlying configuration. When run with no argument it shows the current configuration. When arguments are supplied they are assumed to be configuration tokens, which are strings containing no spaces with the following form: + + [.][=] + +## Setting Configuration Values + +You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `
.` form. + +Example: + +``` +$ qmk config default.keymap=default +default.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## Reading Configuration Values + +You can read configuration values for the entire configuration, a single key, or for an entire section. You can also specify multiple keys to display more than one value. + +### Entire Configuration Example + + qmk config + +### Whole Section Example + + qmk config compile + +### Single Key Example + + qmk config compile.keyboard + +### Multiple Keys Example + + qmk config user compile.keyboard compile.keymap + +## Deleting Configuration Values + +You can delete a configuration value by setting it to the special string `None`. + +Example: + +``` +$ qmk config default.keymap=None +default.keymap: default -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## Multiple Operations + +You can combine multiple read and write operations into a single command. They will be executed and displayed in order: + +``` +$ qmk config compile default.keymap=default compile.keymap=None +compile.keymap=skully +compile.keyboard=clueboard/66_hotswap/gen1 +default.keymap: None -> default +compile.keymap: skully -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# User Configuration Options + +| Key | Default Value | Description | +|-----|---------------|-------------| +| user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | +| user.keymap | None | The keymap name (Example: `default`) | +| user.name | None | The user's github username. | + +# All Configuration Options + +| Key | Default Value | Description | +|-----|---------------|-------------| +| compile.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | +| compile.keymap | None | The keymap name (Example: `default`) | +| hello.name | None | The name to greet when run. | +| new_keyboard.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | +| new_keyboard.keymap | None | The keymap name (Example: `default`) | diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md deleted file mode 100644 index 07f523f578..0000000000 --- a/docs/getting_started_github.md +++ /dev/null @@ -1,65 +0,0 @@ -# How to Use Github with QMK - -Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. - -?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system. - -Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork": - -![Fork on Github](http://i.imgur.com/8Toomz4.jpg) - -If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button: - -![Download from Github](http://i.imgur.com/N1NYcSz.jpg) - -And be sure to select "HTTPS", and select the link and copy it: - -![HTTPS link](http://i.imgur.com/eGO0ohO.jpg) - -From here, enter `git clone --recurse-submodules ` into the command line, and then paste your link: - -``` -user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git -Cloning into 'qmk_firmware'... -remote: Enumerating objects: 9, done. -remote: Counting objects: 100% (9/9), done. -remote: Compressing objects: 100% (5/5), done. -remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874 -Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done. -Resolving deltas: 100% (119972/119972), done. -... -Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b' -Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486' -Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780' -Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d' -Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2' -``` - -You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this: - -``` -user@computer:~$ git add . -user@computer:~$ git commit -m "adding my keymap" -[master cccb1608] adding my keymap - 1 file changed, 1 insertion(+) - create mode 100644 keyboards/planck/keymaps/mine/keymap.c -user@computer:~$ git push -Counting objects: 1, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (1/1), done. -Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. -Total 1 (delta 1), reused 0 (delta 0) -remote: Resolving deltas: 100% (1/1), completed with 1 local objects. -To https://github.com/whoeveryouare/qmk_firmware.git - + 20043e64...7da94ac5 master -> master -``` - -Your changes now exist on your fork on Github - if you go back there (`https://github.com//qmk_firmware`), you can create a "New Pull Request" by clicking this button: - -![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg) - -Here you'll be able to see exactly what you've committed - if it all looks good, you can finalize it by clicking "Create Pull Request": - -![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg) - -After submitting, we may talk to you about your changes, ask that you make changes, and eventually accept it! Thanks for contributing to QMK :) diff --git a/docs/newbs_learn_more_resources.md b/docs/newbs_learn_more_resources.md index 9b77db8fd4..9e33acb0d1 100644 --- a/docs/newbs_learn_more_resources.md +++ b/docs/newbs_learn_more_resources.md @@ -2,14 +2,12 @@ These resources are aimed at giving new members in the QMK community more understanding to the information provided in the Newbs docs. +Command Line resources: + +* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) + Git resources: * [Great General Tutorial](https://www.codecademy.com/learn/learn-git) +* [Flight Rules For Git](https://github.com/k88hudson/git-flight-rules) * [Git Game To Learn From Examples](https://learngitbranching.js.org/) -* [Git Resources to Learn More About Github](getting_started_github.md) -* [Git Resources Aimed Specifically toward QMK](contributing.md) - - -Command Line resources: - -* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) -- cgit v1.2.3