Update keymap/keyboardconfig docs

docs/config_and_keymap.md

@@ -0,0 +1,103 @@
+# Configuring KMK
+
+KMK is configured through a rather large plain-old-Python class called
+`KeyboardConfig`. Subclasses of this configuration exist which pre-fill defaults
+for various known keyboards (for example, many Keebio keyboards are supported
+through our ItsyBitsy to ProMicro pinout adapter). This class is the main
+interface between end users and the inner workings of KMK. Let's dive in!
+
+- Edit or create a file called `main.py` on your `CIRCUITPY` drive. You can also
+  keep this file on your computer (perhaps under `user_keymaps` - please feel
+  free to submit a pull request with your layout definitions!) and copy it over
+  (either manually or, if you're adept with developer tooling and/or a command
+  line, [our
+  Makefile](https://github.com/KMKfw/kmk_firmware/blob/master/docs/flashing.md)).
+  It's definitely recommended to keep a backup of your configuration somewhere
+  that isn't the microcontroller itself - MCUs die, CircuitPython may run into
+  corruption bugs, or you might just have bad luck and delete the wrong file
+  some day.
+
+- Import the `KeyboardConfig` object for your keyboard from `kmk.boards` (or, if
+  handwiring your keyboard, import `KeyboardConfig` from the appropriate MCU for your
+  board from `kmk.mcus`. See `hardware.md` for the list of supported boards and
+  map this to the correct Python module under either of those paths.
+
+- Assign a `KeyboardConfig` instance to a variable (ex. `keyboard = KeyboardConfig()` - note
+  the parentheses)
+
+- Make sure this `KeyboardConfig` instance is actually run at the end of the file with
+  a block such as the following:
+
+```python
+if __name__ == '__main__':
+    keyboard.go()
+```
+
+- Assign pins and your diode orientation (only necessary on handwire keyboards),
+  for example:
+
+```python
+col_pins = (P.SCK, P.MOSI, P.MISO, P.RX, P.TX, P.D4)
+row_pins = (P.D10, P.D11, P.D12, P.D13, P.D9, P.D6, P.D5, P.SCL)
+rollover_cols_every_rows = 4
+diode_orientation = DiodeOrientation.COLUMNS
+```
+
+The pins should be based on whatever CircuitPython calls pins on your particular
+board. You can find these in the REPL on your CircuitPython device:
+
+```python
+import board
+print(dir(board))
+```
+
+> Note: `rollover_cols_every_rows` is only supported with
+> `DiodeOrientation.COLUMNS`, not `DiodeOrientation.ROWS`. It is used for boards
+> such as the Planck Rev6 which reuse column pins to simulate a 4x12 matrix in
+> the form of an 8x6 matrix
+
+- Import the global list of key definitions with `from kmk.keys import KC`. You
+  can either print this out in the REPL as we did with `board` above, or simply
+  look at [our Key
+  documentation](https://github.com/KMKfw/kmk_firmware/blob/master/docs/keycodes.md).
+  We've tried to keep that listing reasonably up to date, but if it feels like
+  something is missing, you may need to read through `kmk/keys.py` (and then
+  open a ticket to tell us our docs are out of date, or open a PR and fix the
+  docs yourself!)
+
+- Define a keymap, which is, in Python terms, a List of Lists of `Key` objects.
+  A very simple keymap, for a keyboard with just two physical keys on a single
+  layer, may look like this:
+
+```python
+keyboard.keymap = [[KC.A, KC.B]]
+```
+
+You can further define a bunch of other stuff:
+
+- `debug_enabled` which will spew a ton of debugging information to the serial
+  console. This is very rarely needed, but can provide very valuable information
+  if you need to open an issue.
+
+- `unicode_mode` from `kmk.consts.UnicodeMode`, which defines the default
+  operating system implementation to use for unicode sequences (see examples
+  below, or `unicode.md`. This can be changed after boot with a key (see
+  `keycodes.md`)
+
+- `tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
+  considering a key "held" (see `keycodes.md`)
+
+- `leader_dictionary`, which defines leader sequences (see `leader.md`), defined
+  as tuples of keycode objects (or you can use
+  `kmk.keycodes.generate_leader_dictionary_seq` with a string)
+
+We also support unicode sequences (emojis, emoticons, umlauted letters,
+whatever) if your operating system and system setup do! See `unicode.md` for
+details.
+
+[Here's a giant example of all the
+above](https://github.com/KMKfw/kmk_firmware/blob/master/user_keymaps/klardotsh/klarank_featherm4.py).
+This is my personal 4x12 matrix layout running on a Planck Rev6 PCB, with a
+Feather M4 Express wired up to the outer matrix pins (in somewhat of a "spider"
+setup), utilizing most of the above features - it's one of the "kitchen sink
+tester" definitions we use on the KMK Core team.