[doc] Add content to "writing a theme"

docs/FAQ.rst

@@ -13,10 +13,12 @@ Then, please open a bug report and I will try to fix the issue quickly.
 If that is not an acceptable solution, here are different ways to step
 back to the last stable version:
 
-(TODO)
+git
-- git
+  ``git checkout v1.10``
-- PIP
+pip
-- AUR
+  ``pip install --user --force-reinstall bumblebee-status==1.10``
+aur
+  TODO
 
 My bar doesn’t show any background colors
 -----------------------------------------

docs/development/theme.rst

@@ -109,24 +109,67 @@ enclosing the actual text.
 Full list of attributes
 -----------------------
 
-(TODO: Add explanation)
+This list specifies the names of all attributes, their JSON type and a short description.
 
--  defaults
+defaults, object
--  cycle
+  Container to specify fallback values, in case nothing more specific matches.
--  icons
+  Can itself contain any of the other attributes (to e.g. specify a default background
--  warning
+  color).
--  critical
+cycle, array of objects
--  fg
+  Similar to defaults, but specifies a list of containers that is iterated for each
--  bg
+  widget being drawn. Effectively, this allows alternating attribute values for 
--  separator
+  widgets (for a powerline effect, for example)
--  padding
+icons, array of strings
--  pango
+  Allows loading of external JSON files and merging them into the current one (adding fields
--  prefix
+  that do not exist in the current JSON, but not overwriting existing values). In practice, this
--  suffix
+  is used to load common icon sets (hence the name).
--  default-separators
+warning, object
--  separator-block-width
+  Specifies attributes such as foreground or background colors for a widget that is in state
--  <module name>
+  "warning"
--  <state>
+critical, object
+  Specifies attributes such as foreground or background colors for a widget that is in state
+  "critical"
+fg, string
+  Specifies foreground (text) color
+bg, string
+  Specifies background (block) color
+separator, string
+  Specifies a string that will be used as separator between two widgets
+padding, string
+  Specifies a string that will be used as padding at the beginning and end of each widget
+pango, object
+  Specifies `pango <https://developer.gnome.org/platform-overview/stable/tech-pango.html>`_ markup
+  attributes. Once this attribute is encountered, all other text formatting, such as `fg` or `bg`
+  are ignored for this widget!
+prefix, string
+  Specifies a string that will be used as prefix for matching widgets
+suffix, string
+  Specifies a string that will be used as suffix for matching widgets
+default-separators, boolean
+  If set to true, the default i3bar separators are drawn, otherwise not
+separator-block-width, integer
+  Specifies the width of the i3bar default separators, if they are drawn
+<module name>, object
+  Container to specify values matching a specific module
+<state>, object
+  Container to specify values matching a specific state of a widget
+
+Note that it is also possible to nest containers, for example, it is possible to embed a "state"
+object inside a specific "module" object to have formatting specific to one module, depending
+on the state of a widget.
+
+In concrete terms, this is used, for example, by multiple mediaplayer modules (cmus, deadbeef, etc.)
+to have specific formatting for play/pause, etc, for that single widget only, like this:
+
+.. code-block:: json
+
+    {
+        "cmus": {
+            "playing": {
+                "prefix": "play"
+            }
+        }
+    }
 
 Examples
 --------