[docs] significant revamp - add sphinx support

make it possible to compile documentation via sphinx - main change is to
use RST instead of MarkDown for most files.

docs/development/theme.rst

@@ -0,0 +1,132 @@
+How to write a new theme
+========================
+
+Introduction
+------------
+
+``bumblebee-status`` themes are simply JSON files that describe various
+attributes (foreground color, background color, etc.) of the blocks that
+make up a status bar.
+
+It is possible to specify each attribute at various levels: - For a
+specific state of a specific module - For a specific module - A cycle of
+attributes (those are cycled through widget-by-widget) - Default values
+
+Looking up a value follows the “more specific rather than more generic”
+approach. In other words, if a foreground color exists for the “warning”
+state of module “a”, any less specific foreground color value that
+**would** match will be ignored.
+
+Themes are loaded from the following locations: -
+``$(BUMBLEBEE_STATUS_BASE_DIR)/themes/`` -
+``~/.config/bumblebee-status/themes/``
+
+Basic structure
+---------------
+
+A very simple theme file looks like this:
+
+.. code:: json
+
+   {
+       "icons": [ "awesome-fonts" ],
+       "defaults": {
+           "fg": "#000000",
+           "bg": "#ffffff",
+           "warning": {
+               "fg": "#ff0000",
+               "bg": "#ffffff"
+           }
+       }
+   }
+
+Icons
+-----
+
+Using the ``icons`` directive, it’s possible to reuse icon definitions
+for multiple themes. The value of the field is the **basename** of a
+JSON file located in ``$(THEME_DIRECTORY)/icons/``. The format of the
+icon file is identical to the theme itself (as the two are essentially
+just merged into a single JSON.
+
+Color definitions and pyWAL support
+-----------------------------------
+
+``bumblebee-status`` supports
+`github:dylanaraps/pywal <https://github.com/dylanaraps/pywal>`__
+definitions.
+
+To make use of them, simply generate a colorset using pyWAL and
+reference it in the theme like this:
+
+.. code:: json
+
+   {
+       "icons": [ ],
+       "colors": [ "wal" ],
+       "defaults": {
+           "critical": {
+               "fg": "cursor",
+               "bg": "color5"
+           },
+           "warning": {
+               "fg": "cursor",
+               "bg": "color6"
+           },
+       } 
+   }
+
+Additionally, you can use the ``colors`` directive to set up named
+colors for your scheme:
+
+.. code:: json
+
+   {
+       "icons": [ ],
+       "colors": [ { "red": "#ff0000", "green": "#00ff00", "black": "#000000" } ],
+       "defaults": {
+           "critical": {
+               "fg": "red",
+               "bg": "black"
+           }
+   }
+
+Pango support
+-------------
+
+All values that accept a full text (i.e. the base level, ``prefix`` and
+``suffix``) accept a special attribute ``pango`` **instead** of all
+other attributes. In other words, if you specify ``pango``, any other
+attribute on that level (foreground color, etc.) will be ignored!
+
+Inside ``pango``, you can just specify arbitrary Pango attributes, and
+those will be applied to a ``<span></span>`` that’s automatically
+enclosing the actual text.
+
+Full list of attributes
+-----------------------
+
+(TODO: Add explanation)
+
+-  defaults
+-  cycle
+-  icons
+-  warning
+-  critical
+-  fg
+-  bg
+-  separator
+-  padding
+-  pango
+-  prefix
+-  suffix
+-  default-separators
+-  separator-block-width
+-  <module name>
+-  <state>
+
+Examples
+--------
+
+see
+`github:tobi-wan-kenobi/bumblebee-status/themes <https://github.com/tobi-wan-kenobi/bumblebee-status/tree/master/themes>`__