[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/index.rst

@@ -0,0 +1,16 @@
+Developer's Guide
+============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   module
+   theme
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/development/module.rst

@@ -0,0 +1,160 @@
+How to write a new module
+=========================
+
+Introduction
+------------
+
+Adding a new module to ``bumblebee-status`` is straight-forward:
+
+-  Add a new Python module in ``modules/contrib/``. The name of the
+   module will be the name that the user needs to specify when invoking
+   ``bumblebee-status`` (i.e. a module called
+   ``modules/contrib/test.py`` will be loaded using
+   ``bumblebee-status -m test``)
+-  See below for how to actually write the module
+-  Test (run ``bumblebee-status`` in the CLI)
+-  Make sure your changes don’t break anything: ``./coverage.sh``
+-  If you want to do me favour, run your module through
+   ``black -t py34`` before submitting
+
+Pull requests
+-------------
+
+The project **gladly** accepts PRs for bugfixes, new functionality, new
+modules, etc. When you feel comfortable with what you’ve developed,
+please just open a PR, somebody will look at it eventually :) Thanks!
+
+Coding guidelines
+-----------------
+
+I’m pretty open to whatever style you use, but if it’s all the same to
+you (and yes, I know that the current codebase is only slowly adapting
+to this): - Please favour single quotes for strings (except for
+docstrings, which are always """) - For private methods/variables,
+please use a leading ``__`` (e.g. ``__output`` rather than ``_output``)
+
+Hello world
+-----------
+
+This example will show “hello world” in the status bar:
+
+.. code:: python
+
+   """Short description"""
+
+   import core.module
+   import core.widget
+
+   class Module(core.module.Module):
+       def __init__(self, config):
+           super().__init__(config, core.widget.Widget(self.full_text))
+
+       def full_text(self, widgets):
+           return 'hello world'
+
+   # vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
+
+Of modules and widgets
+----------------------
+
+There are two important concepts for module writers: - A module is
+something that offers a single set of coherent functionality - A module
+has 1 to n “widgets”, which translates to individual blocks in the i3bar
+
+Very often, this is a 1:1 relationship, and a single module has a single
+widget. If that’s the case for you, you can stop reading now :)
+
+Otherwise, you have a number of ways to handle widgets: - During the
+``super().init__(...)`` inside the module’s constructor, you can specify
+a **list** of widgets, and those will comprise the widgets (in ordered
+fashion) - During runtime, you can set a new list of widgets by using
+the ``self.widgets(<new list>)`` method of the module
+
+Adding widgets at runtime
+-------------------------
+
+If you want to add widgets during runtime, please use the
+``add_widget()`` method of the module:
+
+::
+
+   def do_something(self):
+       self.add_widget(full_text="my sample text", name="<optional name>")
+
+TODO: expand on this
+
+Periodic updates
+----------------
+
+``bumblebee-status`` modules have two different ways to update their
+data: 1. Each interval, the callback registered when the widget was
+created is called. You can do arbitrarily complex things there 2. Each
+interval, **before** the widget’s callback is invoked, a generic
+``update(self, widgets)`` method is called on the **module**
+
+Largely, where you want to put your update code is up to you. My
+observations: - If you want to change the widgets a module has, you
+**have** to stick with ``update()`` - For simple modules, doing the data
+update in the widget callback is simplest (see ``kernel``, for example)
+
+Advanced topics
+---------------
+
+Event handlers
+~~~~~~~~~~~~~~
+
+The ``core.input`` module can be used to execute callbacks during mouse
+events:
+
+.. code:: python
+
+   import core.module
+   import core.widget
+   import core.input
+
+   class Module(core.module.Module):
+       @core.decorators.every(minutes=60, seconds=20)
+       def __init__(self, config):
+           super().__init__(config=config, widgets=<widgets>)
+
+           core.input.register(widget, button=core.input.LEFT_MOUSE, cmd=<cmd>)
+
+The command can be either a CLI tool that will be directly executed
+(e.g. ``cmd='shutdown -h now'``) or a method that will be executed. The
+method’s signature needs to be: ``def <name>(self, event)``, where
+“event” is the event data provided by i3wm.
+
+The full list of possible bindings: - LEFT_MOUSE - RIGHT_MOUSE -
+MIDDLE_MOUSE - WHEEL_UP - WHEEL_UP
+
+Setting a default update interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To change the default update interval, you can use a simple decorator:
+
+.. code:: python
+
+   import core.module
+   import core.widget
+   import core.decorators
+
+   class Module(core.module.Module):
+       @core.decorators.every(minutes=60, seconds=20)
+       def __init__(self, config):
+           super().__init__(config=config, widgets=<widgets>)
+
+**NOTE**: This makes the update interval of the module independent of
+what the user configures via ``-i <interval>``! It is still possible to
+override the module’s interval using ``-p <module>.interval=<value>``,
+however.
+
+TODOs
+-----
+
+-  default update interval
+-  scrolling
+-  theme.minwidth
+-  scrolling decorator
+-  theme.exclude
+-  per module update interval -> nice string format
+-  update via events

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>`__