Rearrange the file layout in preparation of becoming a monorepo

Move the documentation to `doc/plugin/LED-AlphaSquare.md`, sources under
`src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of
merging plugins into a single monorepo.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>

README.md

@@ -5,103 +5,4 @@
  [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-LED-AlphaSquare.svg?branch=master
  [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-LED-AlphaSquare
 
-An alphabet for your per-key LEDs, `AlphaSquare` provides a way to display 4x4
+See [doc/plugin/LED-AlphaSquare.md](doc/plugin/LED-AlphaSquare.md) for documentation.
-"pixel" symbols on your keyboard. With this building block, one can build some
-sweet animations, or just show off - the possibilities are almost endless!
-
-## Using the plugin
-
-To use the plugin, one needs to include the header in their Sketch, tell the
-firmware to `use` the plugin, and one way or another, call the `display` method.
-This can be done from a macro, or via the `AlphaSquareEffect` LED mode.
-
-```c++
-#include <Kaleidoscope.h>
-#include <Kaleidoscope-LEDControl.h>
-#include <Kaleidoscope-LED-AlphaSquare.h>
-
-KALEIDOSCOPE_INIT_PLUGINS(LEDControl,
-                          AlphaSquare,
-                          AlphaSquareEffect);
-
-void setup() {
-  Kaleidoscope.setup();
-
-  AlphaSquare.display (Key_A);
-}
-```
-
-## Plugin methods
-
-The plugin provides the `AlphaSquare` object, which has its methods and
-properties listed below, and an `AlphaSquareEffect` LED mode, which has no
-methods or properties other than those provided by all LED modes.
-
-### `.display(key)`
-### `.display(key, col)`
-### `.display(key, row, col)`
-### `.display(key, row, col, color)`
-
-> Display the symbol for `key` at the given row or column, with pixels set to
-> the specified `color`. If `row` is omitted, the first row - `0` is assumed. If
-> the column is omitted, then the third column - `2` - is used.
-> If the `color` is omitted, the plugin will use the global `.color` property.
->
-> The plugin can display the English alphabet, and the numbers from 0 to 9. The
-> symbol will be drawn with the top-left corner at the given position.
->
-> Please consult the appropriate hardware library of your keyboard to see how
-> keys are laid out in rows and columns.
-
-### `.display(symbol)`
-### `.display(symbol, col)`
-### `.display(symbol, row, col)`
-### `.display(symbol, row, col, color)`
-
-> As the previous function, but instead of a key, it expects a 4x4 bitmap in
-> the form of a 16-bit unsigned integer, where the low bit is the top-right
-> corner, the second-lowest bit is to the right of that, and so on.
->
-> The `SYM4x4` macro can be used to simplify creating these bitmaps.
-
-### `.clear(key)`, `.clear(symbol)`
-### `.clear(key, col)`, `.clear(symbol, col)`
-### `.clear(key, col, row)`, `.clear(symbol, col, row)`
-
-> Just like the `.display()` counterparts, except these clear the symbol, by
-> turning the LED pixels it is made up from off.
-
-### `.color`
-
-> The color to use to draw the pixels.
->
-> Defaults to `{ 0x80, 0x80, 0x80 }` (light gray).
-
-## Plugin helpers
-
-### `SYM4x4(...)`
-
-> A helper macro, which can be used to set up custom bitmaps. It expects 16
-> values, a 4x4 square of zeroes and ones. Zeroes are transparent pixels, ones
-> will be colored.
-
-## Extra symbols
-
-There is a growing number of pre-defined symbols available in the
-`kaleidoscope::alpha_square::symbols` namespace. Ok, growing may have been an
-exaggeration, there is only one as of this writing:
-
-### `Lambda`
-
-> A lambda (`λ`) symbol.
-
-## Dependencies
-
-* [Kaleidoscope-LEDControl](https://github.com/keyboardio/Kaleidoscope-LEDControl)
-
-## Further reading
-
-Starting from the [example][plugin:example] is the recommended way of getting
-started with the plugin.
-
- [plugin:example]: https://github.com/keyboardio/Kaleidoscope-LED-AlphaSquare/blob/master/examples/LED-AlphaSquare/LED-AlphaSquare.ino

doc/plugin/LED-AlphaSquare.md

@@ -0,0 +1,109 @@
+# Kaleidoscope-LED-AlphaSquare
+
+An alphabet for your per-key LEDs, `AlphaSquare` provides a way to display 4x4
+"pixel" symbols on your keyboard. With this building block, one can build some
+sweet animations, or just show off - the possibilities are almost endless!
+
+## Using the plugin
+
+To use the plugin, one needs to include the header in their Sketch, tell the
+firmware to `use` the plugin, and one way or another, call the `display` method.
+This can be done from a macro, or via the `AlphaSquareEffect` LED mode.
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-LEDControl.h>
+#include <Kaleidoscope-LED-AlphaSquare.h>
+
+KALEIDOSCOPE_INIT_PLUGINS(LEDControl,
+                          AlphaSquare,
+                          AlphaSquareEffect);
+
+void setup() {
+  Kaleidoscope.setup();
+
+  AlphaSquare.display (Key_A);
+}
+```
+
+## Plugin methods
+
+The plugin provides the `AlphaSquare` object, which has its methods and
+properties listed below, and an `AlphaSquareEffect` LED mode, which has no
+methods or properties other than those provided by all LED modes.
+
+### `.display(key)`
+### `.display(key, col)`
+### `.display(key, row, col)`
+### `.display(key, row, col, color)`
+
+> Display the symbol for `key` at the given row or column, with pixels set to
+> the specified `color`. If `row` is omitted, the first row - `0` is assumed. If
+> the column is omitted, then the third column - `2` - is used.
+> If the `color` is omitted, the plugin will use the global `.color` property.
+>
+> The plugin can display the English alphabet, and the numbers from 0 to 9. The
+> symbol will be drawn with the top-left corner at the given position.
+>
+> Please consult the appropriate hardware library of your keyboard to see how
+> keys are laid out in rows and columns.
+
+### `.display(symbol)`
+### `.display(symbol, col)`
+### `.display(symbol, row, col)`
+### `.display(symbol, row, col, color)`
+
+> As the previous function, but instead of a key, it expects a 4x4 bitmap in
+> the form of a 16-bit unsigned integer, where the low bit is the top-right
+> corner, the second-lowest bit is to the right of that, and so on.
+>
+> The `SYM4x4` macro can be used to simplify creating these bitmaps.
+
+### `.clear(key)`, `.clear(symbol)`
+### `.clear(key, col)`, `.clear(symbol, col)`
+### `.clear(key, col, row)`, `.clear(symbol, col, row)`
+
+> Just like the `.display()` counterparts, except these clear the symbol, by
+> turning the LED pixels it is made up from off.
+
+### `.color`
+
+> The color to use to draw the pixels.
+>
+> Defaults to `{ 0x80, 0x80, 0x80 }` (light gray).
+
+## Plugin helpers
+
+### `SYM4x4(...)`
+
+> A helper macro, which can be used to set up custom bitmaps. It expects 16
+> values, a 4x4 square of zeroes and ones. Zeroes are transparent pixels, ones
+> will be colored.
+
+## Extra symbols
+
+There is a growing number of pre-defined symbols available in the
+`kaleidoscope::plugin::alpha_square::symbols` namespace. Ok, growing may have
+been an exaggeration, there is only one as of this writing:
+
+### `Lambda`
+
+> A lambda (`λ`) symbol.
+
+## Dependencies
+
+* [Kaleidoscope-LEDControl](https://github.com/keyboardio/Kaleidoscope-LEDControl)
+
+## Further reading
+
+Starting from the [example][plugin:example] is the recommended way of getting
+started with the plugin.
+
+ [plugin:example]: https://github.com/keyboardio/Kaleidoscope-LED-AlphaSquare/blob/master/examples/LED-AlphaSquare/LED-AlphaSquare.ino
+
+## Upgrading
+
+Former versions of the plugin used to have extra symbols in the
+`kaleidoscope::alpha_square::symbols` namespace, while current versions have
+them under `kaleidoscope::plugin::alpha_square::symbols`. The old name is
+deprecated, and will be removed by 2019-01-14.

examples/LED-AlphaSquare/LED-AlphaSquare.ino

@@ -75,15 +75,15 @@ const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) {
 
     for (uint8_t step = 0; step <= 0xf0; step += 8) {
       AlphaSquare.color = { step, step, step };
-      AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 2);
+      AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 2);
-      AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 10);
+      AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 10);
       delay(10);
     }
 
     for (uint8_t step = 0xff; step >= 8; step -= 8) {
       AlphaSquare.color = { step, step, step };
-      AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 2);
+      AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 2);
-      AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 10);
+      AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 10);
       delay(10);
     }
     delay(100);

src/Kaleidoscope-LED-AlphaSquare.h

@@ -17,6 +17,6 @@
 
 #pragma once
 
-#include <Kaleidoscope/LED-AlphaSquare.h>
+#include <kaleidoscope/plugin/LED-AlphaSquare.h>
-#include <Kaleidoscope/AlphaSquare-Effect.h>
+#include <kaleidoscope/plugin/AlphaSquare-Effect.h>
-#include <Kaleidoscope/AlphaSquare-Symbols.h>
+#include <kaleidoscope/plugin/AlphaSquare-Symbols.h>

src/kaleidoscope/plugin/AlphaSquare-Effect.cpp

@@ -18,6 +18,7 @@
 #include <Kaleidoscope-LED-AlphaSquare.h>
 
 namespace kaleidoscope {
+namespace plugin {
 
 uint16_t AlphaSquareEffect::length = 1000;
 uint32_t AlphaSquareEffect::end_time_left_, AlphaSquareEffect::end_time_right_;
@@ -67,6 +68,7 @@ EventHandlerResult AlphaSquareEffect::onKeyswitchEvent(Key &mappedKey, byte row,
   return EventHandlerResult::OK;
 }
 
+}
 }
 
-kaleidoscope::AlphaSquareEffect AlphaSquareEffect;
+kaleidoscope::plugin::AlphaSquareEffect AlphaSquareEffect;

src/kaleidoscope/plugin/AlphaSquare-Effect.h

@@ -21,6 +21,7 @@
 #include <Kaleidoscope-LEDControl.h>
 
 namespace kaleidoscope {
+namespace plugin {
 class AlphaSquareEffect : public LEDMode {
  public:
   AlphaSquareEffect(void) {}
@@ -37,5 +38,6 @@ class AlphaSquareEffect : public LEDMode {
   static Key last_key_left_, last_key_right_;
 };
 }
+}
 
-extern kaleidoscope::AlphaSquareEffect AlphaSquareEffect;
+extern kaleidoscope::plugin::AlphaSquareEffect AlphaSquareEffect;

src/kaleidoscope/plugin/AlphaSquare-Symbols.h

@@ -17,9 +17,10 @@
 
 #pragma once
 
-#include <Kaleidoscope/LED-AlphaSquare.h>
+#include <kaleidoscope/plugin/LED-AlphaSquare.h>
 
 namespace kaleidoscope {
+namespace plugin {
 namespace alpha_square {
 namespace symbols {
 
@@ -31,3 +32,8 @@ static constexpr uint16_t Lambda = SYM4x4(1, 0, 0, 0,
 }
 }
 }
+
+// Backwards compatibility
+namespace alpha_square = kaleidoscope::plugin::alpha_square;
+
+}

src/kaleidoscope/plugin/LED-AlphaSquare.cpp

@@ -16,9 +16,10 @@
  */
 
 #include <Kaleidoscope-LED-AlphaSquare.h>
-#include <Kaleidoscope/LED-AlphaSquare-4x4.h>
+#include <kaleidoscope/plugin/LED-AlphaSquare-4x4.h>
 
 namespace kaleidoscope {
+namespace plugin {
 
 static const uint16_t alphabet[] PROGMEM = {
   ALPHASQUARE_SYMBOL_A,
@@ -94,6 +95,7 @@ void AlphaSquare::display(uint16_t symbol, uint8_t row, uint8_t col) {
   display(symbol, row, col, color);
 }
 
+}
 }
 
-kaleidoscope::AlphaSquare AlphaSquare;
+kaleidoscope::plugin::AlphaSquare AlphaSquare;

src/kaleidoscope/plugin/LED-AlphaSquare.h

@@ -32,6 +32,7 @@
               p30 << 12 | p31 << 13 | p32 << 14 | p33 << 15 )
 
 namespace kaleidoscope {
+namespace plugin {
 class AlphaSquare : public kaleidoscope::Plugin {
  public:
   AlphaSquare(void) {}
@@ -77,6 +78,7 @@ class AlphaSquare : public kaleidoscope::Plugin {
   static cRGB color;
 };
 
+}
 }
 
-extern kaleidoscope::AlphaSquare AlphaSquare;
+extern kaleidoscope::plugin::AlphaSquare AlphaSquare;