Tipboard got open-sourced!1.4.0

47 files changed, 2121 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..9826b9d
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Tipboard.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Tipboard.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Tipboard"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Tipboard"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/doc/api.rst b/doc/api.rst
new file mode 100644
index 0000000..50ae7e4
--- /dev/null
+++ b/doc/api.rst
@@ -0,0 +1,216 @@
+===
+API
+===
+
+One of the advantages of Tipboard is flexibility in feeding tiles with data. We
+achieve that by providing a simple, REST API - that way, your feeding scripts
+may be written in any language (Python, Ruby, Bash, Perl, PHP - you name it).
+The only limitation is the format of input data accepted by a given tile type
+(see :ref:`tiles_library` for the details).
+
+To experiment with resources specified below you can use tools like `Advanced
+REST Client <http://chromerestclient.appspot.com/>`_ (Chrome extension), or
+`cURL <http://curl.haxx.se/>`_, if you prefer working from command line. For
+Python programmers, there's an excellent `Requests
+<http://docs.python-requests.org/en/latest/>`_ library, which we strongly
+recommend.
+
+.. _api_key:
+
+API key
+-------
+
+To send anything to your tiles, first you have to get your API key. This unique
+key is generated for you automatically during Tipboard's installation and may
+be read in the ``~/.tipboard/settings-local.py`` file - it is a sequence of
+characters starting with ``API_KEY``, e.g.::
+
+  API_KEY = 'e2c3275d0e1a4bc0da360dd225d74a43'
+
+If you can't see any such string, just add the key manually (it doesn't have
+to be as long and hard to memorise as the one above, though).
+
+.. note::
+
+   Every change in ``settings-local.py`` file requires restart of the
+   application.
+
+Available resources
+-------------------
+
+Current API version: **v0.1**
+
+.. note::
+
+   In 99% of cases, probably only ``push`` and ``tileconfig`` will be of
+   interest to you.
+
+
+.. http:post:: /api/(api_version)/(api_key)/push
+
+   Feeds tiles with data. Input data should be provided in the format that
+   complies with the one used in a desired tile. **Note:** a tile to which data
+   will be sent is defined by the key included in the data sent rather than by
+   `tile_id` as in cases below.
+
+   :param api_version: version of API to be used
+   :param api_key: your API key
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /api/v0.1/my_key/push
+      Host: localhost:7272
+      POST data: tile=text key=id_1 data={"text": "Hello world!"}
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/html; charset=UTF-8
+
+      Tile's data pushed successfully.
+
+.. http:post:: /api/(api_version)/(api_key)/tileconfig/(tile_id)
+
+   Configures tile specified by `tile_id`. The configuration should comply with
+   the specification of a given tile type.
+
+   :param api_version: version of API to be used
+   :param api_key: your API key
+   :param tile_id: unique tile's ID from your ``layout_config.yaml`` file
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/v0.1/my_key/tileconfig/id_1
+      Host: localhost:7272
+      POST data: value={"font_color": "#00FF00"}
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/html; charset=UTF-8
+
+      Tile's config updated.
+
+
+.. http:delete:: /api/(api_version)/(api_key)/tileconfig/(tile_id)
+
+   Resets configuration of the tile specified by `tile_id`.
+
+   :param api_version: version of API to be used
+   :param api_key: your API key
+   :param tile_id: unique tile's ID from your ``layout_config.yaml`` file
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      DELETE /api/v0.1/my_key/tileconfig/id_1
+      Host: localhost:7272
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/html; charset=UTF-8
+
+      Tile's config deleted.
+
+.. http:get:: /api/(api_version)/(api_key)/tiledata/(tile_id)
+
+   Retrieves data belonging to the tile specified by `tile_id`. May be useful for diagnostics.
+
+   :param api_version: version of API to be used
+   :param api_key: your API key
+   :param tile_id: unique tile's ID from your ``layout_config.yaml`` file
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/v0.1/my_key/tiledata/id_1
+      Host: localhost:7272
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json; charset=UTF-8
+
+      {
+          "tile_template": "text",
+          "meta": {
+              "font_color": "#ff9618",
+              "font_size": "45px"
+          },
+          "data": {
+              "text": "Lorem ipsum."
+          },
+          "id": "id_1"
+      }
+
+.. http:delete:: /api/(api_version)/(api_key)/tiledata/(tile_id)
+
+   Removes everything belonging to the tile given by `tile_id` from Redis.
+
+   :param api_version: version of API to be used
+   :param api_key: your API key
+   :param tile_id: unique tile's ID from your ``layout_config.yaml`` file
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      DELETE /api/v0.1/my_key/tiledata/id_1
+      Host: localhost:7272
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/html; charset=UTF-8
+
+      Tile's data deleted.
+
+.. http:get:: /api/(api_version)/(api_key)/info
+
+   Provides information on project and user configuration. This resource has
+   been created for debugging purposes.
+
+   :param api_version: version of API to be used
+   :param api_key: your API key
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/v0.1/my_key/info
+      Host: localhost:7272
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json; charset=UTF-8
+
+      {
+          "tipboard_version": "1.3.0",
+          "project_layout_config": "/home/pylabs/.tipboard/layout_config.yaml",
+          "redis_db": {
+              "host": "localhost",
+              "db": 4,
+              "port": 6379
+          },
+          "project_name": "pylabs"
+      }
diff --git a/doc/changelog.rst b/doc/changelog.rst
new file mode 100644
index 0000000..d9e113e
--- /dev/null
+++ b/doc/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..7fe4c27
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,265 @@
+# -*- coding: utf-8 -*-
+#
+# Tipboard documentation build configuration file, created by
+# sphinx-quickstart on Mon Mar 17 10:55:17 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.todo',
+    'sphinxcontrib.httpdomain',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Tipboard'
+copyright = u'2013-2014, Allegro Group'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.4.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.4.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+html_domain_indices = False
+
+# If false, no index is generated.
+html_use_index = False
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Tipboarddoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'Tipboard.tex', u'Tipboard Documentation',
+   u'Allegro Group', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'tipboard', u'Tipboard Documentation',
+     [u'Allegro Group'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'Tipboard', u'Tipboard Documentation',
+   u'Allegro Group', 'Tipboard', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# -- Misc options ---------------------------------------------------------
+todo_include_todos = True
diff --git a/doc/configuration.rst b/doc/configuration.rst
new file mode 100644
index 0000000..a4d8f0b
--- /dev/null
+++ b/doc/configuration.rst
@@ -0,0 +1,241 @@
+=============
+Configuration
+=============
+
+The description below assumes that you have installed Tipboard correctly and
+use a default configuration that is the starting point for steps presented
+below (see section :ref:`installation`).
+
+Default configuration
+---------------------
+
+Tipboard launched after installation present a basic, empty layout – empty
+tiles in 2 lines with 4 columns each. If you want to modify them, create a
+"clean" config, where your changes will be introduced. Use the command::
+
+  (tb-env)$ tipboard create_project <name_of_project>
+
+It will create the ``~/.tipboard`` dir with the following content:
+
+* ``settings-local.yaml`` file that defines the layout of tiles on the
+  dashboard you are creating;
+
+* ``settings-local.py`` file in which you can overwrite default (global)
+  application settings; a description of options and their default values has
+  been presented in `this file
+  <https://github.com/allegro/tipboard/blob/develop/tipboard/settings.py>`_;
+
+* ``custom_tiles`` subdir to place your own tiles.
+
+.. note::
+
+   Before you send anything to your tiles, you have to get your API key
+   first, which is described in the :ref:`api_key` section.
+
+Launching Tipboard app
+----------------------
+
+After you have logged in to your machine, you may launch Tipboard with the
+command::
+
+  (tb-env)$ tipboard runserver [<host>] [<port>]
+
+...where ``host`` and ``port`` parameters are optional (by default these are
+``localhost`` and ``7272``; if you want the application to listen on all the
+network interfaces, set ``host`` to ``0.0.0.0``).
+
+Customising tile layout
+-----------------------
+
+As mentioned previously, the layout of tiles in a dashboard is defined by
+``layout_config.yaml`` file. The file is in the `YAML <http://yaml.org>`_
+format, the description of which is beyond the scope of this manual. However,
+it is worth indicating that YAML has certain format requirements –
+**indentation should have a unified structure** (be a multiplication of a
+number, e.g. 4), when creating indentations **spaces should not be mixed with
+tabs**.
+
+Below you can find a list of options that can be saved in the file.
+Indentations indicate the position of a given option in the configuration (e.g.
+``details`` are superior to ``page_title``).
+
+::
+
+  details
+      page_tile
+  layout
+      row_X_of_Y
+      col_X_of_Y
+          tile_template
+          tile_id
+          tile
+          timeout
+
+where:
+
+.. describe:: details
+
+   A section that contains additional configuration parameters; for the time
+   being it is only ‘page_title’; depending on his needs, the users add other
+   elements.
+
+.. describe:: page_tile
+
+   A section that defines the title of a page to appear in the web browser
+   after entering the dashboard.
+
+.. describe:: layout
+
+   A section that contains a proper configuration of the tile layout.
+
+.. describe:: row_X_of_Y
+
+   Defines a row hight; a sum of Xs should equal Y.
+
+.. describe:: col_X_of_Y
+
+   Similar to above but concerns a column width in a given row.
+
+.. describe:: tile_template
+
+   The name of a tile template to be displayed (e.g.  ``pie_chart``,
+   ``line_chart``, ``cumulative_flow``)
+
+.. describe:: tile_id
+
+   A tile identifier in a HTML document and key identifier in Redis.
+
+.. describe:: title
+
+   A title to be displayed in the upper part of the tile.
+
+.. describe:: timeout
+
+   The length (in seconds) of data life (if data is not sent during this time,
+   you will be informed that the data is stalled). Since interval used by the
+   application to check for those timeouts is 5 seconds, it doesn't make sense
+   to set this value smaller than this.
+
+   .. versionadded:: 1.3.0
+
+The method of using ``row_X_of_Y`` and ``col_X_of_Y`` has been presented in the
+examples below. If you want to see how it's done "from the kitchen", and you
+have some basic knowledge of CSS styling, have a look `here
+<https://github.com/allegro/tipboard/blob/develop/tipboard/static/css/layout.css>`_;
+
+.. note::
+
+   If you want to present a lot of data on your dashboard, consider dividing
+   all your tiles into two (or more) separate dashboards. Tiles offer a limited
+   capacity and if you "feed" them with too much data (e.g. long lines of
+   text), it is possible the dashboard will get broken.
+
+Setting tiles' rotation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the most useful functions is defining tiles to rotate. In a single
+container (i.e. in one of the fields indicated by ``col_X_of_Y`` and
+``row_X_of_Y``), you may define a few tiles to be displayed in this location as
+items rotating at intervals defined in the configuration (similar to ads
+rotating on bus/tram stops, so-called *citylights*). To achieve that:
+
+* add the ``flip-time-xx`` class to a container, where ``xx`` is rotation
+  interval in seconds;
+* add tile to the container.
+
+The example below presents a container with two tiles (one of the ``empty`` type,
+the other of the ``text`` type) to rotate every 2 seconds (``flip-time-2``).
+The rotation will start with the ``empty`` type tile::
+
+  layout:
+    - row_1_of_2:
+      - col_1_of_4 flip-time-2:
+        - tile_template: empty
+          tile_id: empty
+          title: Empty Tile 2
+
+        - tile_template: text
+          tile_id: text
+          title: Empty Tile
+
+Sample layout
+~~~~~~~~~~~~~
+
+Let's assume we want to define a layout as on the scheme below (i.e. a division
+into 2 equal rows, with the upper one divided into 4 columns, and the lower one
+divided into 3 columns)::
+
+  +-------+--------+--------+-------+
+  |       |        |        |       |
+  |       |        |        |       |
+  |       |        |        |       |
+  |       |        |        |       |
+  +-------+--+-----+----+---+-------+
+  |          |          |           |
+  |          |          |           |
+  |          |          |           |
+  |          |          |           |
+  +----------+----------+-----------+
+
+...its corresponding configuration file should look as follows (for brevity, I
+will present only the ``layout`` section, skipping the ``tile_template``,
+``title_id``, etc.)::
+
+  layout:
+      row_1_of_2:
+          col_1_of_4:
+          col_1_of_4:
+          col_1_of_4:
+          col_1_of_4:
+      row_1_of_2:
+          col_1_of_3:
+          col_1_of_3:
+          col_1_of_3:
+
+Multiple dashboards per application's instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. versionadded:: 1.3.0
+
+It is possible to define multiple dashboards per application's instance. In
+order to achieve that, you just create separate layout config files (one per
+every dashboard) - having done that, your dashboards will be available at::
+
+  http://localhost:7272/<name_of_layout_config_file>
+
+For example, having two layout config files ``my_first_dashboard.yaml`` and
+``my_second_dashboard.yaml``, the corresponding dashboards can be accessed
+via::
+
+  http://localhost:7272/my_first_dashboard
+  http://localhost:7272/my_second_dashboard
+
+.. note::
+
+   You have to strip the ``.yaml`` file extension when constructing your URLs.
+
+When it comes to feeding those dashboards with data, the future data location
+is specified by tile IDs (unique within application instance). Therefore, there
+is no need to specify different URLs for different dashboards - having tiles'
+IDs, Tipboard will make sure that your data is delivered where it should be.
+
+Multiple rotating dashboards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.3.0
+
+If you have defined several dashboards (as described above), you may want to
+rotate (flip) them periodically. If you are unsure what that means, think of
+extensions like Revolver (Chrome) or Tab Slideshow (Firefox).
+
+To achieve that, you need:
+
+* at least two dashboards (well, that's kind of obvious)
+* in the file ``settings-local.py`` add the variable ``FLIPBOARD_INTERVAL =
+  <seconds>`` (e.g. ``FLIPBOARD_INTERVAL = 5``)
+
+The above solution will make all your dashboards rotate - if you want to limit
+this behavior and rotate only certain dashboards, just add another parameter
+``FLIPBOARD_SEQUENCE`` which is just a list of dashboard names that should be
+taken into account, e.g.::
+
+  FLIPBOARD_SEQUENCE = ['my_first_dashboard', 'my_third_dashboard']
diff --git a/doc/extras.rst b/doc/extras.rst
new file mode 100644
index 0000000..396fb35
--- /dev/null
+++ b/doc/extras.rst
@@ -0,0 +1,58 @@
+======
+Extras
+======
+
+Here you will find description of components which are not a part of the
+Tipboard project *per se*, although they may be useful to some of its users.
+Assuming standard installation, you can find them here::
+
+  <path_to_your_virtualenv>/lib/python2.7/site-packages/tipboard/extras
+
+.. note::
+
+   If you have developed something of similar nature and you are willing to
+   share it, we encourage you to make a pull request to our repo. Thanks!
+
+``jira-ds.py``
+--------------
+
+Script for fetching frequently used data from `JIRA
+<https://www.atlassian.com/software/jira>`_ issue tracker, in order to present
+it on your dashboards.  Returns requested data to stdout in JSON format. For
+the list of available options see ``jira-ds.py --help``.
+
+This script is basically a wrapper around ``jira-ds.js``, so those two files
+shouldn't be separated. Requires `CasperJS <http://casperjs.org/>`_ and
+`PhantomJS <http://phantomjs.org/>`_ installed somewhere in your path (we
+suggest using `npm <http://nodejs.org/>`_ for that).
+
+Before you start using them, remember to fill in ``JIRA_CREDENTIALS`` and
+``JIRA_BASE_URL`` (in ``jira-ds.py``) as well as ``url_jira`` and
+``url_jira_login`` (in ``jira-ds.js``) with the your JIRA credentials, location
+of your JIRA instance and its login page.
+
+Tested with JIRA 6.1.x.
+
+
+``client_code_example.py``
+--------------------------
+
+Simple Python script targeted to novice users serving as an example how to glue
+together three steps: fetching data, processing it and then sending it to the
+tile. See comments in the source code for further explaination.
+
+
+``fabfile.py``
+--------------
+
+Script for quick, automated installations on remote machines.
+
+You need to have `fabric <https://github.com/ronnix/fabtools>`_ and
+`fabtools <http://fabtools.readthedocs.org>`_ to use remote install script.
+
+Run::
+
+  fab -H root@host install
+
+-- it will install all needed ``.deb`` packages, create virualenv and set up
+Tipboard service using master branch from our main repo.
diff --git a/doc/img/advanced-plot.png b/doc/img/advanced-plot.png
new file mode 100644
index 0000000..94da500
--- /dev/null
+++ b/doc/img/advanced-plot.png
diff --git a/doc/img/bar-chart.png b/doc/img/bar-chart.png
new file mode 100644
index 0000000..7cf3048
--- /dev/null
+++ b/doc/img/bar-chart.png
diff --git a/doc/img/big-value.png b/doc/img/big-value.png
new file mode 100644
index 0000000..b59bb52
--- /dev/null
+++ b/doc/img/big-value.png
diff --git a/doc/img/cumulative-flow.png b/doc/img/cumulative-flow.png
new file mode 100644
index 0000000..13c9aaa
--- /dev/null
+++ b/doc/img/cumulative-flow.png
diff --git a/doc/img/fancy-listing.png b/doc/img/fancy-listing.png
new file mode 100644
index 0000000..e5ab907
--- /dev/null
+++ b/doc/img/fancy-listing.png
diff --git a/doc/img/just-value.png b/doc/img/just-value.png
new file mode 100644
index 0000000..43458d4
--- /dev/null
+++ b/doc/img/just-value.png
diff --git a/doc/img/line-chart.png b/doc/img/line-chart.png
new file mode 100644
index 0000000..9bf030d
--- /dev/null
+++ b/doc/img/line-chart.png
diff --git a/doc/img/listing.png b/doc/img/listing.png
new file mode 100644
index 0000000..0bedee5
--- /dev/null
+++ b/doc/img/listing.png
diff --git a/doc/img/norm-chart.png b/doc/img/norm-chart.png
new file mode 100644
index 0000000..15bf7bd
--- /dev/null
+++ b/doc/img/norm-chart.png
diff --git a/doc/img/pie-chart.png b/doc/img/pie-chart.png
new file mode 100644
index 0000000..20521fa
--- /dev/null
+++ b/doc/img/pie-chart.png
diff --git a/doc/img/simple-percentage.png b/doc/img/simple-percentage.png
new file mode 100644
index 0000000..2a86b31
--- /dev/null
+++ b/doc/img/simple-percentage.png
diff --git a/doc/img/smaller/advanced-plot.png b/doc/img/smaller/advanced-plot.png
new file mode 100644
index 0000000..d11f307
--- /dev/null
+++ b/doc/img/smaller/advanced-plot.png
diff --git a/doc/img/smaller/bar-chart.png b/doc/img/smaller/bar-chart.png
new file mode 100644
index 0000000..34241f6
--- /dev/null
+++ b/doc/img/smaller/bar-chart.png
diff --git a/doc/img/smaller/big-value.png b/doc/img/smaller/big-value.png
new file mode 100644
index 0000000..7516c43
--- /dev/null
+++ b/doc/img/smaller/big-value.png
diff --git a/doc/img/smaller/cumulative-flow.png b/doc/img/smaller/cumulative-flow.png
new file mode 100644
index 0000000..c0cfd5a
--- /dev/null
+++ b/doc/img/smaller/cumulative-flow.png
diff --git a/doc/img/smaller/fancy-listing.png b/doc/img/smaller/fancy-listing.png
new file mode 100644
index 0000000..b241ac6
--- /dev/null
+++ b/doc/img/smaller/fancy-listing.png
diff --git a/doc/img/smaller/just-value.png b/doc/img/smaller/just-value.png
new file mode 100644
index 0000000..d3c8cf0
--- /dev/null
+++ b/doc/img/smaller/just-value.png
diff --git a/doc/img/smaller/line-chart.png b/doc/img/smaller/line-chart.png
new file mode 100644
index 0000000..2873303
--- /dev/null
+++ b/doc/img/smaller/line-chart.png
diff --git a/doc/img/smaller/listing.png b/doc/img/smaller/listing.png
new file mode 100644
index 0000000..0b11eb9
--- /dev/null
+++ b/doc/img/smaller/listing.png
diff --git a/doc/img/smaller/norm-chart.png b/doc/img/smaller/norm-chart.png
new file mode 100644
index 0000000..739ffcd
--- /dev/null
+++ b/doc/img/smaller/norm-chart.png
diff --git a/doc/img/smaller/pie-chart.png b/doc/img/smaller/pie-chart.png
new file mode 100644
index 0000000..d312bdf
--- /dev/null
+++ b/doc/img/smaller/pie-chart.png
diff --git a/doc/img/smaller/simple-percentage.png b/doc/img/smaller/simple-percentage.png
new file mode 100644
index 0000000..790b77a
--- /dev/null
+++ b/doc/img/smaller/simple-percentage.png
diff --git a/doc/img/smaller/text.png b/doc/img/smaller/text.png
new file mode 100644
index 0000000..6819889
--- /dev/null
+++ b/doc/img/smaller/text.png
diff --git a/doc/img/text.png b/doc/img/text.png
new file mode 100644
index 0000000..b47e9c6
--- /dev/null
+++ b/doc/img/text.png
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..15ebda9
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,16 @@
+Welcome to Tipboard's documentation!
+====================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   installation
+   configuration
+   tiles
+   api
+   extras
+   changelog
+   license
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 0000000..9f16ff0
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,98 @@
+.. _installation:
+
+==============
+How to install
+==============
+
+You can install Tipboard on a variety of sensible operating systems. This guide
+assumes **Ubuntu Server 12.04 LTS** and presents shell command examples
+accordingly.
+
+Prerequisites
+-------------
+
+Tipboard requires Python 2.7 which can be installed with this command::
+
+  $ sudo apt-get install python-dev python-virtualenv
+
+Another dependency which needs to be satisfied  before proceeding further is
+`Redis <http://redis.io/>`_ server::
+
+  $ sudo apt-get install redis-server
+
+Optional yet recommended packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of such packages is ``supervisor`` - it facilitates program administration
+(e.g. its reboot), especially if there are a few instances launched on the
+machine.
+
+Based on the Tornado framework, Tipboard has a built-in server available, but
+a typical use case assumes communication with the world via reverse proxy (e.g.
+using ``nginx`` or ``apache``).
+
+.. note::
+
+   Although configuration of reverse proxy is out of scope of this manual, we
+   would like to emphasise that Tipboard use Web Sockets – a relatively new
+   mechanism – and thus you should ensure a server in a version that will
+   support it (e.g. ``nginx`` >= 1.3.13 or ``apache2`` >= 2.4.6). By default
+   Ubuntu 12.04 offers older versions – you may then use backports.
+
+.. note::
+
+   It will be useful to have an updated version of ``pip`` (i.e. >= 1.4) and
+   ``virtualenv`` (i.e. >= 1.10).
+
+Preparing environment for installation
+--------------------------------------
+
+Start by creating a user, the privileges of whom will be used by the
+application (for the needs of this manual, let's create the user "pylabs")::
+
+  $ sudo adduser pylabs --home /home/pylabs --shell /bin/bash
+  $ sudo su - pylabs
+
+Virtual environment
+~~~~~~~~~~~~~~~~~~~
+
+Continue by creating a virtual environment that will help you conveniently
+separate your instance from what you already have installed in the system
+(let's say we name it "tb-env")::
+
+  $ cd /home/pylabs
+  $ virtualenv tb-env
+
+Activate the created virtual environment with the following command::
+
+  $ source /home/pylabs/tb-env/bin/activate
+
+.. note::
+
+   It is worth saving the above line in the ``~/.profile`` file. As a result,
+   the virtual environment will be activated automatically whenever you log in
+   on the machine.
+
+.. note::
+
+   Further setup assumes an activated virtual environment, which is denoted by
+   ``(tb-env)`` prefix in your shell prompt.
+
+Installing with pip
+-------------------
+
+After creating and activating virtualenv, install the latest (current) version
+of Tipboard package available on pypi ("Python Package Index") with the
+following command::
+
+  (tb-env)$ pip install tipboard
+
+Verification
+------------
+
+To verify if installation has been successful, launch this command::
+
+  (tb-env)$ tipboard runserver
+
+If you see the message "Listening on port..." instead of errors, it means that
+installation was successful and you may proceed to the next section.
diff --git a/doc/license.rst b/doc/license.rst
new file mode 100644
index 0000000..d8e3824
--- /dev/null
+++ b/doc/license.rst
@@ -0,0 +1,5 @@
+License
+_______
+
+.. include:: ../LICENSE.rst
+    :literal:
diff --git a/doc/overview.rst b/doc/overview.rst
new file mode 100644
index 0000000..dc3f75f
--- /dev/null
+++ b/doc/overview.rst
@@ -0,0 +1,21 @@
+Overview
+--------
+
+Tipboard is a system for creating dashboards, written in JavaScript and Python.
+Its widgets ('tiles' in Tipboard's terminology) are completely separated from
+data sources, which provides great flexibility and relatively high degree of
+possible customizations.
+
+Because of its intended target (displaying various data and statistics in your
+office), it is optimized for larger screens.
+
+Similar projects: `Geckoboard <http://www.geckoboard.com/>`_,
+`Dashing <http://shopify.github.io/dashing/>`_.
+
+Project assumptions
+~~~~~~~~~~~~~~~~~~~
+
+#. Defining a dashboard layout (number of lines, columns, types of tiles etc.).
+#. Clear separation between tiles and data sources.
+#. Ability to create own tiles and scripts querying data sources (e.g. Jira, Bamboo, Confluence etc.).
+#. Feeding tiles via REST API.
diff --git a/doc/tile__advanced_plot.rst b/doc/tile__advanced_plot.rst
new file mode 100644
index 0000000..afeabab
--- /dev/null
+++ b/doc/tile__advanced_plot.rst
@@ -0,0 +1,140 @@
+=================
+``advanced_plot``
+=================
+
+.. image:: img/smaller/advanced-plot.png
+
+**Description**
+
+This tile is for more demanding users. It basically allows to display arbitrary
+type of chart/plot from the `jqPlot <http://www.jqplot.com/>`_ library, along
+with the title and description (both are optional).
+
+Before you start experimenting with jqPlot library, we suggest to familiarize
+yourself with `this manual
+<http://www.jqplot.com/docs/files/usage-txt.html#jqPlot_Usage>`_. After that
+you should check out `options tutorial
+<http://www.jqplot.com/docs/files/optionsTutorial-txt.html#Options_Tutorial>`_
+and `options summary <http://www.jqplot.com/docs/files/jqplot-core-js.html>`_.
+
+Here you will find `some examples <http://www.jqplot.com/deploy/dist/examples/>`_.
+
+**Content**
+
+::
+
+  "data" = {
+      "title": "<tile>",
+      "description": "<description>",
+      "plot_data": "<data>"
+  }
+
+where:
+
+.. describe:: title, description
+
+   Title and description (subtitle) for the tile.
+
+.. describe:: plot_data
+
+   Data that will be fed directly to your plot. Its form depends on the
+   specific type of plot that you are going to use - see jqPlot's documentation
+   for the details.
+
+Example (using horizontal `Bar Chart
+<http://www.jqplot.com/deploy/dist/examples/barTest.html>`_ - third example
+from the top)::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=advanced_plot"
+       -d "key=<tile_id>"
+       -d 'data={"title": "Metric Tons per Year", "description": "",
+                 "plot_data": [[[2,1], [4,2], [6,3], [3,4]],
+                               [[5,1], [1,2], [3,3], [4,4]],
+                               [[4,1], [7,2], [1,3], [2,4]]]}'
+
+.. note::
+
+   Keep in mind that ``advanced_plot`` can display arbitrary charts from jqPlot
+   library, and more than often they are quite different when it comes to the
+   parameters required etc.
+
+**Configuration**
+
+::
+
+  value = {
+    "value": "<jqplot_config>"
+  }
+
+where:
+
+.. describe:: value
+
+   Raw configuration that will be passed directly to jqPlot and which should
+   obey the rules defined by the jqPlot library. Internally, this config will
+   be passed as ``$.jqplot(some-container, some-data, our-config)``.
+
+   If such configuration contains one of jqPlot's renderers, its name should be
+   passed as a string, according to the table below:
+
+   +--------------------------------------+-------------------------------+
+   | jqPlot's renderer                    | string to send                |
+   +======================================+===============================+
+   | ``$.jqplot.BarRenderer``             | ``"BarRenderer"``             |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.BlockRenderer``           | ``"BlockRenderer"``           |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.BubbleRenderer``          | ``"BubbleRenderer"``          |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.CanvasAxisLabelRenderer`` | ``"CanvasAxisLabelRenderer"`` |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.CanvasAxisTickRenderer``  | ``"CanvasAxisTickRenderer"``  |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.CanvasTextRenderer``      | ``"CanvasTextRenderer"``      |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.CategoryAxisRenderer``    | ``"CategoryAxisRenderer"``    |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.DateAxisRenderer``        | ``"DateAxisRenderer"``        |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.DonutRenderer``           | ``"DonutRenderer"``           |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.EnhancedLegendRenderer``  | ``"EnhancedLegendRenderer"``  |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.FunnelRenderer``          | ``"FunnelRenderer"``          |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.LogAxisRenderer``         | ``"LogAxisRenderer"``         |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.MekkoAxisRenderer``       | ``"MekkoAxisRenderer"``       |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.MekkoRenderer``           | ``"MekkoRenderer"``           |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.MeterGaugeRenderer``      | ``"MeterGaugeRenderer"``      |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.OhlcRenderer``            | ``"OhlcRenderer"``            |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.PieRenderer``             | ``"PieRenderer"``             |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.PyramidAxisRenderer``     | ``"PyramidAxisRenderer"``     |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.PyramidGridRenderer``     | ``"PyramidGridRenderer"``     |
+   +--------------------------------------+-------------------------------+
+   | ``$.jqplot.PyramidRenderer``         | ``"PyramidRenderer"``         |
+   +--------------------------------------+-------------------------------+
+
+Example (using horizontal `Bar Chart
+<http://www.jqplot.com/deploy/dist/examples/barTest.html>`_ - third example
+from the top)::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+       -X POST
+       -d 'value={
+              "seriesDefaults": {
+                  "trendline": {"show": false},
+                  "renderer":"BarRenderer",
+                  "pointLabels": {"show": true, "location": "e", "edgeTolerance": -15},
+                  "shadowAngle": 135,
+                  "rendererOptions": {"barDirection": "horizontal"}
+              },
+              "axes": {"yaxis": { "renderer": "CategoryAxisRenderer"}}}'
diff --git a/doc/tile__bar_chart.rst b/doc/tile__bar_chart.rst
new file mode 100644
index 0000000..47dfd32
--- /dev/null
+++ b/doc/tile__bar_chart.rst
@@ -0,0 +1,61 @@
+=============
+``bar_chart``
+=============
+
+.. image:: img/smaller/bar-chart.png
+
+**Description**
+
+Tile displaying data in the form of horizontal bar charts. Each cart may
+consist of one or more series of data - in the latter case, such bars are
+grouped respectively. There are no "hard" limits when it comes to the number of
+charts/series, although we suggest to keep them down to 3 charts of 2 series
+each.
+
+**Content**
+
+::
+
+  data = {
+      "title": "<title>",
+      "subtitle": "<subtitle>",
+      "ticks": ["<label1>", "<label2>", "<label3>" ...],
+      "series_list": [[<val1>, <val2>, <val3>, ...],
+                      [<val1>, <val2>, <val3>, ...]]
+  }
+
+where:
+
+.. describe:: title, subtitle
+
+   Title and subtitle displayed on the top of the tile.
+
+.. describe:: ticks
+
+   Labels to be displayed on the left side of the charts.
+
+.. describe:: series_list
+
+   List of series, as name suggests. ``[[1, 2]]`` will give one chart of two
+   bars, ``[[3, 4, 5], [6, 7, 8]]`` will give two charts of three bars each.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=bar_chart"
+       -d "key=<tile_id>"
+       -d 'data={"title": "The A-Team",
+                 "subtitle": "Velocity (Last tree sprints)",
+                 "ticks": ["n-2", "n-1", "Last (n)"],
+                 "series_list": [[49, 50, 35], [13, 45, 9]]}'
+
+**Configuration**
+
+This tile does not offer any configuration options.
+
+.. note::
+
+   In case of displaying more than one charts on the same tile, the number of
+   values in ``series_list`` for every chart should be the same (and they
+   should be equal to the number of ``ticks``.
diff --git a/doc/tile__big_value.rst b/doc/tile__big_value.rst
new file mode 100644
index 0000000..dbdcad2
--- /dev/null
+++ b/doc/tile__big_value.rst
@@ -0,0 +1,97 @@
+=============
+``big_value``
+=============
+
+.. image:: img/smaller/big-value.png
+
+**Description**
+
+This is a variation of ``simple_percentage`` tile. It has slightly different
+footer (four possible values instead of just two; values are displayed on the
+right side of the label instead of below), and the main value (``big_value``)
+is little bit bigger.
+
+**Content**
+
+::
+
+  data = {
+      "title": "<title>",
+      "description": "<description>",
+      "big-value": "<value>",
+      "upper-left-label": "<label>",
+      "upper-left-value": "<value>",
+      "lower-left-label": "<label>",
+      "lower-left-value": "<value>",
+      "upper-right-label": "<label>",
+      "upper-right-value": "<value>",
+      "lower-right-label": "<label>",
+      "lower-right-value": "<value>"
+  }
+
+where:
+
+.. describe:: title, description
+
+   Title and description (subtitle) for the tile.
+
+.. describe:: big_value
+
+   Main value, which treated as a string, so it can contain symbols like ``%`` etc.
+
+.. describe:: upper-left-value, lower-left-value, upper-right-value, lower-right-value
+
+   Smaller, bottom-left and bottom-right values.
+
+.. describe:: upper-left-label, lower-left-label, upper-right-label, lower-right-label
+
+   Labels for above values.
+
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=big_value"
+       -d "key=<tile_id>"
+       -d 'data={"title": "Tickets",
+                 "description": "number of blockers",
+                 "big-value": "314",
+                 "upper-left-label": "critical:",
+                 "upper-left-value": "1020",
+                 "lower-left-label": "major:",
+                 "lower-left-value": "8609",
+                 "upper-right-label": "minor:",
+                 "upper-right-value": "7532",
+                 "lower-right-label": "all:",
+                 "lower-right-value": "19 853"}'
+
+**Configuration**
+
+::
+
+  value = {
+      "big_value_color": "<color>",
+      "fading_background": <BOOLEAN>
+  }
+
+where:
+
+.. describe:: big_value_color
+
+   Background color for ``big_value`` in a hexadecimal form or color name (e.g.
+   ``#94C140`` or ``green``).
+
+.. describe:: fading_background
+
+   Turns on/off background pulsation for ``big_value`` (may be useful for
+   alerts etc.).
+
+   .. versionadded:: 1.3.0
+
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+         -X POST
+         -d 'value={"big_value_color": "green", "fading_background": true}'
diff --git a/doc/tile__cumulative_flow.rst b/doc/tile__cumulative_flow.rst
new file mode 100644
index 0000000..c26d46a
--- /dev/null
+++ b/doc/tile__cumulative_flow.rst
@@ -0,0 +1,68 @@
+===================
+``cumulative_flow``
+===================
+
+.. image:: img/smaller/cumulative-flow.png
+
+**Description**
+
+Cumulative chart using `jqPlot <http://www.jqplot.com/>`_ library. Allows to
+display up to seven plots on a single chart.
+
+**Content**
+
+::
+
+  data = {
+      "title": "<title>",
+      "series_list": [{"label": "<label1>", "series": [<val1>, <val2>, ...]},
+                      {"label": "<label2>", "series": [<val1>, <val2>, ...]}]
+  }
+
+where:
+
+.. describe:: title
+
+   Title to be displayed above the labels.
+
+.. describe:: series_list
+
+   A container (i.e. list of objects) for the data; each such object
+   corresponding to a single plot consists of two keys: ``label`` and
+   ``series``, where the latter is a list of values constructing the plot.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=cumulative_flow"
+       -d "key=<tile_id>"
+       -d 'data={"title": "My title:",
+                 "series_list": [{"label": "label 1", "series": [ 0, 0, 0, 0, 1, 1, 2, 2, 1, 1, 1, 0, 0, 2, 0 ]},
+                                 {"label": "label 2", "series": [ 0, 5, 0, 0, 1, 0, 0, 3, 0, 0, 0, 7, 8, 9, 1 ]}]}'
+
+**Configuration**
+
+::
+
+  value = {"ticks": [[<key>, "<value>"], [<key>, "<value>"], ... ]}
+
+where:
+
+.. describe:: ticks
+
+   List of elements defining x-axis; each such element is a list of form ``[k,
+   v]`` where ``k`` is an oridinal number designating position of such tick and
+   ``v`` is a string which will be displayed in that place.
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+        -X POST
+        -d 'value={"ticks": [[1, "mon"], [2, "tue"], [3, "wed"], [4, "thu"], [5, "fri"], [6, "sat"], [7, "sun"]]}'
+
+.. note::
+
+   If ``series_list`` contains more than one object (which is the case 99% of
+   the time), each one of them should have ``series`` list of the same length -
+   and this lenght should be equal to the number of ``ticks``.
diff --git a/doc/tile__fancy_listing.rst b/doc/tile__fancy_listing.rst
new file mode 100644
index 0000000..902bdc9
--- /dev/null
+++ b/doc/tile__fancy_listing.rst
@@ -0,0 +1,91 @@
+=================
+``fancy_listing``
+=================
+
+.. image:: img/smaller/fancy-listing.png
+
+**Description**
+
+This tile is a more sophisticated version of ``listing`` tile offering colored
+labels and centering options. Each entry is an object containing three keys:
+``label``, ``text`` and ``description``. Threrefore, ``data`` (i.e. content) is
+just a list of such objects.
+
+**Content**
+
+::
+
+  "data" = [
+      {"label": "<label1>", "text": "<entry1>", "description": "<desc1>" },
+      {"label": "<label2>", "text": "<entry2>", "description": "<desc2>" }
+  ]
+
+where:
+
+.. describe:: label
+
+   Smaller label displayed on the left which can be colored.
+
+.. describe:: text
+
+   A textual entry to be displayed next to the label.
+
+.. describe:: description
+
+   Subtitle displayed below ``text`` element.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=fancy_listing"
+       -d "key=<tile_id>"
+       -d 'data=[{"label": "My label 1", "text": "Lorem ipsum", "description": "such description" },
+                 {"label": "My label 2", "text": "Dolor sit", "description": "yet another" },
+                 {"label": "My label 3", "text": "Amet", "description": "" }]'
+
+**Configuration**
+
+::
+
+  value = {
+      "vertical_center": <BOOLEAN>,
+      "<position>": {
+          "label_color": "<color>",
+          "center": <BOOLEAN>
+      },
+  }
+
+where:
+
+.. describe:: vertical_center
+
+   Centers vertically all the entries (along with their labels).
+
+   .. versionadded:: 1.3.0
+
+.. describe:: position
+
+   Tells which entry (starting from 1) should be a subject to ``label_color``
+   and ``center`` (specified as subkeys of ``position``).
+
+   .. describe:: label_color
+
+      Sets the color of label for the entry given with ``position``. Color can
+      be specified in a hexadecimal form (``#RRGGBB``) or by name (e.g.
+      ``green``).
+
+   .. describe:: center
+
+      Centers horizontally entry's ``text`` and ``description`` (it does not
+      affect label's position).
+
+      .. versionadded:: 1.3.0
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+         -X POST
+         -d 'value={"vertical_center": true,
+                    "1": {"label_color": "red", "center": true},
+                    "3": {"label_color": "green", "center": true }}'
diff --git a/doc/tile__just_value.rst b/doc/tile__just_value.rst
new file mode 100644
index 0000000..0d76082
--- /dev/null
+++ b/doc/tile__just_value.rst
@@ -0,0 +1,67 @@
+==============
+``just_value``
+==============
+
+.. image:: img/smaller/just-value.png
+
+**Description**
+
+Tile for displaying single, short information with a possibility to change its
+background color.
+
+**Content**
+
+::
+
+  "data" = {
+      "title": "<title>",
+      "description": "<description>",
+      "just-value": "<value>"
+  }
+
+where:
+
+.. describe:: title, description
+
+   Title and description (subtitle) for the tile.
+
+.. describe:: just-value
+
+   Value to be displayed on the tile, with optionally colored background.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=just_value"
+       -d "key=<tile_id>"
+       -d 'data={"title": "Next release:", "description": "(days remaining)", "just-value": "23"}'
+
+**Configuration**
+
+::
+
+  value = {
+      "just-value-color": "<color>",
+      "fading_background": <BOOLEAN>
+  }
+
+where:
+
+.. describe:: just-value-color
+
+   Background color for ``just-value`` in a hexadecimal form or color name (e.g.
+   ``#94C140`` or ``green``).
+
+.. describe:: fading_background
+
+   Turns on/off background pulsation for ``just-value`` (may be useful for
+   alerts etc.).
+
+   .. versionadded:: 1.3.0
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+         -X POST
+         -d 'value={"just-value-color": "green", "fading_background": true}'
diff --git a/doc/tile__line_chart.rst b/doc/tile__line_chart.rst
new file mode 100644
index 0000000..a7435b1
--- /dev/null
+++ b/doc/tile__line_chart.rst
@@ -0,0 +1,81 @@
+==============
+``line_chart``
+==============
+
+.. image:: img/smaller/line-chart.png
+
+**Description**
+
+Line-chart using `jqPlot <http://www.jqplot.com/>`_ library. Allows to display
+arbitrary number of plots on single chart, with automatical generation of trend
+lines for them (which is turned on by default).
+
+**Content**
+
+::
+
+  data = {
+      "subtitle": "<subtitle_text">,
+      "description": "<description_text>",
+      "series_list": [[<series1>], [<series2>], [<series3>], ...]
+  }
+
+where:
+
+.. describe:: subtitle, description
+
+   Additional text fields for charts descriptions (optional - you can pass
+   empty strings here).
+
+.. describe:: series_list
+
+   Data for line-charts in a form of list of series, where each series
+   designates single chart; each element of a given series is a pair
+   ``[x_axis_value, y_axis_value]``.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=line_chart"
+       -d "key=example_line"
+       -d 'data={"subtitle": "averages from last week",
+                 "description": "Sales in our dept",
+                 "series_list": [[["23.09", 8326], ["24.09", 260630], ["25.09", 240933], ["26.09", 229639], ["27.09", 190240], ["28.09", 125272], ["29.09", 3685]],
+                                 [["23.09", 3685], ["24.09", 125272], ["25.09", 190240], ["26.09", 229639], ["27.09", 240933], ["28.09", 260630], ["29.09", 108326]]]}'
+
+-- this will give two plots on a single chart (on x-axis there will be "23.09",
+"24.09", "25.09" and so on) with heading "Sales in our dept" and subtitle
+"averages from last week".
+
+**Configuration**
+
+::
+
+  value = {<jqplot_config>}
+
+where:
+
+.. describe:: jqplot_config
+
+   Configuration params in the form described by `jqPlot documentation
+   <http://www.jqplot.com/tests/line-charts.php>`_.
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/example_line
+         -X POST
+         -d 'value={"grid": {"drawGridLines": true,
+                             "gridLineColor": "#FFFFFF",
+                             "shadow": false,
+                             "background": "#000000",
+                             "borderWidth": 0}}'
+
+-- this will set up the grid (in white color), black background and will turn
+off shadow effects as well as borders.
+
+.. note::
+
+   In case of displaying multiple plots on a single chart (e.g. for more than
+   one data series) you have to keep in mind that the ``x_axis_value`` values
+   should be the same for all of those plots.
diff --git a/doc/tile__listing.rst b/doc/tile__listing.rst
new file mode 100644
index 0000000..dbe2516
--- /dev/null
+++ b/doc/tile__listing.rst
@@ -0,0 +1,34 @@
+===========
+``listing``
+===========
+
+.. image:: img/smaller/listing.png
+
+**Description**
+
+Very simple tile for displaying list of entries (up to seven) of arbitrary
+content. For more sophisticated needs there is a ``fancy_listing`` tile.
+
+**Content**
+
+::
+
+  data = {"items": ["<entry1>", "<entry2>", ..., "<entry7>"]}
+
+where:
+
+.. describe:: items
+
+   List of items (entries) to display.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=listing"
+       -d "key=<tile_id>"
+       -d "data={"items": ["Leader: 5", "Product Owner: 0", "Scrum Master: 3", "Developer: 0"]}"
+
+**Configuration**
+
+This tile does not offer any configuration options.
diff --git a/doc/tile__norm_chart.rst b/doc/tile__norm_chart.rst
new file mode 100644
index 0000000..6cfd8c0
--- /dev/null
+++ b/doc/tile__norm_chart.rst
@@ -0,0 +1,79 @@
+==============
+``norm_chart``
+==============
+
+.. image:: img/smaller/norm-chart.png
+
+.. versionadded:: 1.3.0
+
+**Description**
+
+"Curve vs norm" style chart. Suitable for situations, when you want to
+compare some data with expected value ("norm") or put an emphasis on y-axis
+values.
+
+**Content**
+
+::
+
+    "data" = {
+        "title": "<title>",
+        "description": "<description>",
+        "plot_data": [ [<series1>], [<series2>], [<series3>], ... ]
+    }
+
+where:
+
+.. describe:: title, description
+
+   Title and description (subtitle) for the tile.
+
+.. describe:: plot_data
+
+    Data for charts in a form of list of series, where each series designates
+    single chart; each element of a given series is a pair ``[x_axis_value,
+    y_axis_value]``.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=norm_chart"
+       -d "key=<tile_id>"
+       -d 'data={"title": "My title",
+                 "description": "Some description",
+                 "plot_data": [[[1, 2], [3, 5.12], [5, 13.1], [7, 33.6], [9, 85.9], [11, 219.9]],
+                               [[6, 2], [3, 5.12], [5, 13.1], [7, 33.6], [9, 85.9], [11, 219.9]]]}'
+
+**Configuration**
+
+::
+
+  value = {
+      "easyNorms": [["<color>", <y-value>, <line_width>], ...]
+  }
+
+where:
+
+.. describe:: easyNorms
+
+   List of norms to be displayed. Each norm consists of three elements:
+
+   .. describe:: color
+
+      Color which given norm should use - in a hexadecimal form or color name
+      (e.g.  ``#94C140`` or ``green``).
+
+   .. describe:: y-value
+
+      Value for the norm.
+
+   .. describe:: line_width
+
+      Line thickness for the norm (in pixels).
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+         -X POST
+         -d 'value={"easyNorms": [["yellow", 200, 2], ["green", 100, 2]]}'
diff --git a/doc/tile__pie_chart.rst b/doc/tile__pie_chart.rst
new file mode 100644
index 0000000..afd8f84
--- /dev/null
+++ b/doc/tile__pie_chart.rst
@@ -0,0 +1,64 @@
+=============
+``pie_chart``
+=============
+
+.. image:: img/smaller/pie-chart.png
+
+**Description**
+
+"Pie-chart" style chart using `jqPlot <http://www.jqplot.com/>`_ library, with
+optional legend.
+
+**Content**
+
+::
+
+  data = {
+      "title": "<optional_title>",
+      "pie_data": [[identifier1, value1], [identifier2, value2], ...]
+  }
+
+where:
+
+.. describe:: title
+
+   Chart's title (optional).
+
+.. describe:: pie_data
+
+   Data for pie-chart in a form of list of lists, where each sub-list is an
+   identifier-value pair. Percentage of the whole chart shared by given part is
+   calculated automatically by jqPlot - relatively to the sum of values of all
+   parts.
+
+Example::
+
+  curl http//localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=pie_chart"
+       -d "key=example_pie"
+       -d 'data={"title": "My title", "pie_data": [["Pie 1", 25], ["Pie 2", 25], ["Pie 3", 50]]}'
+
+-- this will result in a pie-chart with title "My title", divided by three
+parts "Pie 1", "Pie 2" and "Pie 3".
+
+**Configuration**
+
+::
+
+  value = {<jqplot_config>}
+
+where:
+
+.. describe:: jqplot_config
+
+   Configuration params in the form described by `jqPlot documentation
+   <http://www.jqplot.com/tests/pie-donut-charts.php>`_.
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tild_id>
+         -X POST
+         -d 'value={"title": true, "legend": {"show": true, "location": "s"}}'
+
+-- this will result in a pie-chart with legend turned on at the bottom of the tile (``s`` stands for "south") - its title will be turned on as well.
diff --git a/doc/tile__simple_percentage.rst b/doc/tile__simple_percentage.rst
new file mode 100644
index 0000000..d0fbdc7
--- /dev/null
+++ b/doc/tile__simple_percentage.rst
@@ -0,0 +1,81 @@
+=====================
+``simple_percentage``
+=====================
+
+.. image:: img/smaller/simple-percentage.png
+
+**Description**
+
+Tile displaying three arbitrary values (with labels) - one bigger ("main"
+value) and two smaller (at the bottom-left and bottom-right of the tile). It is
+possible to change background color for the main value.
+
+**Content**
+
+::
+
+  data = {
+      "title":       "<title>",
+      "subtitle":    "<subtitle>",
+      "big_value":   "<value1>",
+      "left_value":  "<value2>",
+      "right_value": "<value3>"
+      "left_label":  "<label1>",
+      "right_label": "<label2>"
+  }
+
+where:
+
+.. describe:: title, subtitle
+
+   They serve as a label for the ``big_value`` ("main" value).
+
+.. describe:: big_value
+
+   Main value, which treated as a string, so it can contain symbols like ``%`` etc.
+
+.. describe:: left_value, right_value
+
+   Smaller, bottom-left and bottom-right values.
+
+.. describe:: left_label, right_label
+
+   Labels for above values.
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=simple_percentage"
+       -d "key=<tile_id>"
+       -d 'data={"title": "My title", "subtitle": "My subtitle", "big_value": "100%",
+                 "left_value": "50%", "left_label": "smaller label 1",
+                 "right_value": "25%", "right_label": "smaller label 2"}'
+
+**Configuration**
+
+::
+
+  value = {
+      "big_value_color": "<color>",
+      "fading_background": <BOOLEAN>
+  }
+
+where:
+
+.. describe:: big_value_color
+
+   Background color for ``big_value`` in a hexadecimal form or color name (e.g.
+   ``#94C140`` or ``green``).
+
+.. describe:: fading_background
+
+   Turns on/off background pulsation for ``big_value`` (may be useful for alerts etc.).
+
+   .. versionadded:: 1.3.0
+
+Example::
+
+  curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id>
+       -X POST
+       -d 'value={"big_value_color": "green", "fading_background": true}'
diff --git a/doc/tile__text.rst b/doc/tile__text.rst
new file mode 100644
index 0000000..e9318a7
--- /dev/null
+++ b/doc/tile__text.rst
@@ -0,0 +1,61 @@
+========
+``text``
+========
+
+.. image:: img/smaller/text.png
+
+**Description**
+
+Simple text-tile designated to display... (surprise!) text.
+
+**Content**
+
+::
+
+  data = {"text": "<text_content>"}
+
+where:
+
+.. describe:: text_content
+
+   A textual content to be displayed.
+
+Example::
+
+  curl http://localhot:7272/api/v0.1/<api_key>/push
+       -X POST
+       -d "tile=text"
+       -d "key=mytext"
+       -d 'data={"text": "Hello world!"}'
+
+**Configuration**
+
+::
+
+  value = {"<config_element>": "<config_value>"}
+
+where:
+
+.. describe:: config_element
+
+   One of three attributes of displayed text (i.e. ``font_size``, ``color`` and
+   ``font_weight``).
+
+.. describe:: config_value
+
+   Value matching above.
+
+Example::
+
+    curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/mytext
+         -X POST
+         -d 'value={"font_color": "#00FF00"}'
+
+.. note::
+
+   Parameter ``font_size`` can be specified in two ways - as a number (e.g.
+   ``"font_size": 10``) or as a string (e.g. ``"font_size": "10px"``) - both of
+   them have the same effect.
+
+   Keys ``font_size``, ``color``, ``font_weight`` with empty ``config_value``
+   are ignored (in such case, they will inherit those values from parent CSS).
diff --git a/doc/tiles.rst b/doc/tiles.rst
new file mode 100644
index 0000000..0855a2f
--- /dev/null
+++ b/doc/tiles.rst
@@ -0,0 +1,99 @@
+=====
+Tiles
+=====
+
+Every tile consists of an obligatory ``.html`` file and two optional ``.css``
+and ``.js`` files. All three files belonging to a tile should have the same
+name that corresponds with the tile name – e.g. with the ``pie_chart`` tile
+these are ``pie_chart.html``, ``pie_chart.css`` and ``pie_chart.js`` files
+respectively.
+
+Customising tiles
+-----------------
+
+If you want to modify a tile (e.g. change a CSS attribute, which obviously
+cannot be done via API), copy a desired file in the folder of tiles delivered
+with the application (i.e.
+``<path_to_your_virtualenv>/lib/python2.7/site-packages/tipboard/tiles``),
+paste it in your tile folder (i.e. ``~/.tipboard/custom_tiles``) and edit
+according to your needs.
+
+Files in your ``custom_tiles`` folder take precedence over those shipped by
+default with the application and thus you can easily replace desired elements
+(e.g. if you want to change the text colour, just copy and edit the ``.css``
+file – without touching ``.html`` and ``.js`` files). We plan to introduce a
+command simplifying this process in the future.
+
+Color palette
+-------------
+
+Color palette used by Tipboard's tiles is defined as shown in the table below.
+To retain consistency, we strongly suggest sticking to them while customising
+tiles.
+
++-------------+---------------------+
+| Value       | Name                |
++=============+=====================+
+| ``#000000`` | ``black``           |
++-------------+---------------------+
+| ``#FFFFFF`` | ``white``           |
++-------------+---------------------+
+| ``#25282D`` | ``tile_background`` |
++-------------+---------------------+
+| ``#DC5945`` | ``red``             |
++-------------+---------------------+
+| ``#FF9618`` | ``yellow``          |
++-------------+---------------------+
+| ``#94C140`` | ``green``           |
++-------------+---------------------+
+| ``#12B0C5`` | ``blue``            |
++-------------+---------------------+
+| ``#9C4274`` | ``violet``          |
++-------------+---------------------+
+| ``#EC663C`` | ``orange``          |
++-------------+---------------------+
+| ``#54C5C0`` | ``naval``           |
++-------------+---------------------+
+
+Common elements
+---------------
+
+* tile's content (``data`` key) and its configuration (``value`` key) should be
+  send as two separate requests - once you have established desired
+  configuration it does not make much sense to send it over and over again;
+* in order to reset tile's config, you just send an empty ``value`` key (e.g.
+  ``value = {}``).
+
+.. _tiles_library:
+
+Library of available tiles
+--------------------------
+
+In the following pages we present a "library" of available tiles (i.e. those
+bundled with the application), which should serve as a specification how to
+send data to them and how to set up its configuration options.
+
+.. toctree::
+   :maxdepth: 2
+
+   tile__text
+   tile__pie_chart
+   tile__line_chart
+   tile__cumulative_flow
+   tile__simple_percentage
+   tile__listing
+   tile__bar_chart
+   tile__fancy_listing
+   tile__big_value
+   tile__just_value
+   tile__advanced_plot
+   tile__norm_chart
+
+.. note::
+
+   In order to keep brevity, all examples presented in specifications above do
+   not include any escape characters. Therefore, it's up to you to insert them
+   where necessary.
+
+   And also, remember to set all the elements in angle brackets (e.g.
+   ``<api_key>``, ``<tile_id>`` etc.) to reflect your configuration.