From 86f6405574d75cdc69c32829cb523aa1538ecd77 Mon Sep 17 00:00:00 2001 From: skullY Date: Tue, 25 Feb 2020 09:17:24 -0800 Subject: [PATCH] More sidebar organization --- docs/_summary.md | 155 ++++++++++-------- ...figuration.md => cli_dev_configuration.md} | 2 +- docs/getting_started_github.md | 65 -------- docs/newbs_learn_more_resources.md | 14 +- 4 files changed, 90 insertions(+), 146 deletions(-) rename docs/{cli_configuration.md => cli_dev_configuration.md} (94%) delete mode 100644 docs/getting_started_github.md diff --git a/docs/_summary.md b/docs/_summary.md index dee8a3198..994d58557 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_dev_configuration.md similarity index 94% rename from docs/cli_configuration.md rename to docs/cli_dev_configuration.md index ad9ff291c..1196ab669 100644 --- a/docs/cli_configuration.md +++ b/docs/cli_dev_configuration.md @@ -4,7 +4,7 @@ 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. +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 diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md deleted file mode 100644 index 07f523f57..000000000 --- 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 9b77db8fd..9e33acb0d 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. -Git resources: - -* [Great General Tutorial](https://www.codecademy.com/learn/learn-git) -* [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) + +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/)