first documentation for plugins

CHANGELOG.rst

@@ -31,6 +31,7 @@ not released yet
   status of an event with a symbol (e.g. `✓` for accepted, `✗` for declined,
   `?` for tentative); partication status is shown for the email addresses
   configured for the event's calendar
+* NEW support for color theme, command, and formatter plugins
 
 0.11.2
 ======

doc/source/hacking.rst

@@ -31,6 +31,36 @@ Before we will accept your PR, we will ask you to:
  * make sure your patch conforms with :pep:`008` (should be covered by passing
    tests)
 
+Plugins
+-------
+
+Khal now supports plugins, currently for supporting new commands (`example
+command plugin`_), formatting (`example formatting plugin`), and
+colors (`example color plugin`).
+
+If you want to develop a new feature, please check if it can be implemented as
+a plugin.  If you are unsure, please ask us, we will gladly help you and, if
+needed, also extend the plugin API.  We would like to see new functionality
+matured in plugins before we consider integrating it into khal's core.
+
+.. _`example command plugin`: https://github.com/geier/khal_navigate
+.. _`example formatting plugin`: https://github.com/tcuthbert/khal/tree/plugin/example
+.. _`example color plugin`: https://github.com/geier/khal_gruvbox/tree/importlib
+
+
+Color scheme plugins
+*********************
+
+Khal color schemes plugins are only availlable for the `ikhal` interface. They
+are installed as python packages (e.g. `python -m pip install khal_gruvbox`).
+A color scheme plugin must provide an entry point `khal_colorscheme` and contain
+an urwid palette definition. The palette definition is a list of tuples, where
+each tuple contains an attribute name and a color definition.  See the `urwid
+documentation`_ for more information. All currently avaialable attributes can be
+found in `khal's source code`_.
+
+.. _`urwid documentation`: http://urwid.org/manual/displayattributes.html
+.. _`khal's source code`: https://github.com/pimutils/khal/blob/master/khal/ui/colors.py
 
 General notes for developing khal (and lots of other python packages)
 ---------------------------------------------------------------------

khal/settings/khal.spec

@@ -255,20 +255,9 @@ blank_line_before_day = boolean(default=False)
 
 # Choose a color theme for khal.
 #
-# This is very much work in progress. Help is really welcome! The two currently
-# available color schemes (*dark* and *light*) are defined in
-# *khal/ui/colors.py*, you can either help improve those or create a new one
-# (see below). As ikhal uses urwid, have a look at `urwid's documentation`__
-# for how to set colors and/or at the existing schemes. If you cannot change
-# the color of an element (or have any other problems) please open an issue on
-# github_.
-#
-# If you want to create your own color scheme, copy the structure of the
-# existing ones, give it a new and unique name and also add it as an option in
-# `khal/settings/khal.spec` in the section `[default]` of the property `theme`.
-#
-# __ http://urwid.org/manual/displayattributes.html
-# .. _github: https://github.com/pimutils/khal/issues
+# Khal ships with two color themes, *dark* and *light*.  Additionally, plugins
+# might supply different color schemes.
+# You can also define your own color theme in the [palette] section.
 theme = string(default='dark')
 
 # Whether to show a visible frame (with *box drawing* characters) around some