Adding upstream version 2.8.3.upstream/2.8.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

52 files changed, 4174 insertions, 0 deletions

diff --git a/docs/source/_static/css/theme_overrides.css b/docs/source/_static/css/theme_overrides.css
new file mode 100644
index 0000000..7e39e34
--- /dev/null
+++ b/docs/source/_static/css/theme_overrides.css
@@ -0,0 +1,6 @@
+.wy-table-responsive > table > tbody > tr > td {
+	white-space: unset;
+}
+.wy-table-responsive > table > tbody > tr > td:first-child {
+	vertical-align: top;
+}
diff --git a/docs/source/_static/img/icons/cross.png b/docs/source/_static/img/icons/cross.png
new file mode 100644
index 0000000..33a3837
--- /dev/null
+++ b/docs/source/_static/img/icons/cross.png
diff --git a/docs/source/_static/img/icons/error.png b/docs/source/_static/img/icons/error.png
new file mode 100644
index 0000000..dbfda22
--- /dev/null
+++ b/docs/source/_static/img/icons/error.png
diff --git a/docs/source/_static/img/icons/tick.png b/docs/source/_static/img/icons/tick.png
new file mode 100644
index 0000000..c277e6b
--- /dev/null
+++ b/docs/source/_static/img/icons/tick.png
diff --git a/docs/source/_static/img/pl-mode-insert.png b/docs/source/_static/img/pl-mode-insert.png
new file mode 100644
index 0000000..9b09e18
--- /dev/null
+++ b/docs/source/_static/img/pl-mode-insert.png
diff --git a/docs/source/_static/img/pl-mode-normal.png b/docs/source/_static/img/pl-mode-normal.png
new file mode 100644
index 0000000..29d3716
--- /dev/null
+++ b/docs/source/_static/img/pl-mode-normal.png
diff --git a/docs/source/_static/img/pl-mode-replace.png b/docs/source/_static/img/pl-mode-replace.png
new file mode 100644
index 0000000..d7c89a4
--- /dev/null
+++ b/docs/source/_static/img/pl-mode-replace.png
diff --git a/docs/source/_static/img/pl-mode-visual.png b/docs/source/_static/img/pl-mode-visual.png
new file mode 100644
index 0000000..d654763
--- /dev/null
+++ b/docs/source/_static/img/pl-mode-visual.png
diff --git a/docs/source/_static/img/pl-truncate1.png b/docs/source/_static/img/pl-truncate1.png
new file mode 100644
index 0000000..c687502
--- /dev/null
+++ b/docs/source/_static/img/pl-truncate1.png
diff --git a/docs/source/_static/img/pl-truncate2.png b/docs/source/_static/img/pl-truncate2.png
new file mode 100644
index 0000000..1630f1d
--- /dev/null
+++ b/docs/source/_static/img/pl-truncate2.png
diff --git a/docs/source/_static/img/pl-truncate3.png b/docs/source/_static/img/pl-truncate3.png
new file mode 100644
index 0000000..83e5b21
--- /dev/null
+++ b/docs/source/_static/img/pl-truncate3.png
diff --git a/docs/source/commands.rst b/docs/source/commands.rst
new file mode 100644
index 0000000..a35d05f
--- /dev/null
+++ b/docs/source/commands.rst
@@ -0,0 +1,9 @@
+**************************************
+Powerline shell commands’ manual pages
+**************************************
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   commands/*
diff --git a/docs/source/commands/config.rst b/docs/source/commands/config.rst
new file mode 100644
index 0000000..3fc25aa
--- /dev/null
+++ b/docs/source/commands/config.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+powerline-config manual page
+============================
+
+.. automan:: powerline.commands.config
+   :prog: powerline-config
+
+See also
+--------
+
+:manpage:`powerline(1)`
diff --git a/docs/source/commands/daemon.rst b/docs/source/commands/daemon.rst
new file mode 100644
index 0000000..d899c73
--- /dev/null
+++ b/docs/source/commands/daemon.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+powerline-daemon manual page
+============================
+
+.. automan:: powerline.commands.daemon
+   :prog: powerline-daemon
+
+See also
+--------
+
+:manpage:`powerline(1)`
diff --git a/docs/source/commands/lint.rst b/docs/source/commands/lint.rst
new file mode 100644
index 0000000..92d676d
--- /dev/null
+++ b/docs/source/commands/lint.rst
@@ -0,0 +1,14 @@
+:orphan:
+
+.. _command-powerline-lint:
+
+powerline-lint manual page
+==========================
+
+.. automan:: powerline.commands.lint
+   :prog: powerline-lint
+
+See also
+--------
+
+:manpage:`powerline(1)`, :manpage:`powerline-config(1)`
diff --git a/docs/source/commands/main.rst b/docs/source/commands/main.rst
new file mode 100644
index 0000000..178bcb9
--- /dev/null
+++ b/docs/source/commands/main.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+powerline manual page
+=====================
+
+.. automan:: powerline.commands.main
+   :prog: powerline
+
+See also
+--------
+
+:manpage:`powerline-daemon(1)`, :manpage:`powerline-config(1)`
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..5577ef6
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,70 @@
+# vim:fileencoding=utf-8:noet
+from __future__ import (unicode_literals, division, absolute_import, print_function)
+
+import os
+import sys
+
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(os.getcwd()))))
+sys.path.insert(0, os.path.abspath(os.getcwd()))
+
+extensions = [
+	'powerline_autodoc', 'powerline_automan',
+	'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode',
+]
+source_suffix = '.rst'
+master_doc = 'index'
+project = 'Powerline'
+version = 'beta'
+release = 'beta'
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+
+html_theme = 'default'
+html_static_path = ['_static']
+html_show_copyright = False
+
+latex_show_urls = 'footnote'
+latex_elements = {
+	'preamble': '''
+		\\DeclareUnicodeCharacter{22EF}{$\\cdots$}   % Dots
+		\\DeclareUnicodeCharacter{2665}{\\ding{170}} % Heart
+		\\DeclareUnicodeCharacter{2746}{\\ding{105}} % Snow
+		\\usepackage{pifont}
+	''',
+}
+
+man_pages = []
+for doc in os.listdir(os.path.join(os.path.dirname(__file__), 'commands')):
+	if doc.endswith('.rst'):
+		name = doc[:-4]
+		module = 'powerline.commands.{0}'.format(name)
+		get_argparser = __import__(str(module), fromlist=[str('get_argparser')]).get_argparser
+		parser = get_argparser()
+		description = parser.description
+		man_pages.append([
+			'commands/' + name,
+			'powerline' if name == 'main' else 'powerline-' + name,
+			description,
+			'',
+			1
+		])
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we’re building docs locally
+	try:
+		import sphinx_rtd_theme
+		html_theme = 'sphinx_rtd_theme'
+		html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+	except ImportError:
+		pass
+
+if on_rtd or html_theme == 'sphinx_rtd_theme':
+	html_context = {
+		'css_files': [
+			'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
+			'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
+			'_static/css/theme_overrides.css',
+		],
+	}
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
new file mode 100644
index 0000000..a2be2d5
--- /dev/null
+++ b/docs/source/configuration.rst
@@ -0,0 +1,151 @@
+*******************************
+Configuration and customization
+*******************************
+
+.. note::
+   **Forking the main GitHub repo is not needed to personalize Powerline 
+   configuration!** Please read through the :ref:`quick-guide` for a quick 
+   introduction to user configuration.
+
+Powerline is configured with one main configuration file, and with separate 
+configuration files for themes and colorschemes. All configuration files are 
+written in JSON, with the exception of segment definitions, which are 
+written in Python.
+
+Powerline provides default configurations in the following locations:
+
+:ref:`Main configuration <config-main>`
+    :file:`{powerline}/config.json`
+:ref:`Colorschemes <config-colorschemes>`
+    :file:`{powerline}/colorschemes/{name}.json`, 
+    :file:`{powerline}/colorschemes/{extension}/__main__.json`, 
+    :file:`{powerline}/colorschemes/{extension}/{name}.json`
+:ref:`Themes <config-themes>`
+    :file:`{powerline}/themes/{top_theme}.json`, 
+    :file:`{powerline}/themes/{extension}/__main__.json`, 
+    :file:`{powerline}/themes/{extension}/default.json`
+
+Here `{powerline}` is one of the following:
+
+#. The default configuration directory located in the main package: 
+   :file:`{powerline_root}/powerline/config_files`. May be absent in some 
+   packages (e.g. when installing via Gentoo ebuilds).
+#. If variable ``$XDG_CONFIG_DIRS`` is set and non-empty then to any 
+   :file:`{directory}/powerline` where `{directory}` is a directory listed in 
+   a colon-separated ``$XDG_CONFIG_DIRS`` list. Directories are checked in 
+   reverse order.
+#. User configuration directory located in :file:`$XDG_CONFIG_HOME/powerline`. 
+   This usually corresponds to :file:`~/.config/powerline` on all platforms.
+
+If per-instance configuration is needed please refer to :ref:`Local 
+configuration overrides <local-configuration-overrides>`.
+
+.. _configuration-merging:
+
+.. note::
+   Existing multiple configuration files that have the same name, but are placed 
+   in different directories, will be merged. Merging happens in the order given 
+   in the above list of possible `{powerline}` meanings.
+
+   When merging configuration only dictionaries are merged and they are merged 
+   recursively: keys from next file overrule those from the previous unless 
+   corresponding values are both dictionaries in which case these dictionaries 
+   are merged and key is assigned the result of the merge.
+
+.. note:: Some configuration files (i.e. themes and colorschemes) have two level
+    of merging: first happens merging described above, second theme- or 
+    colorscheme-specific merging happens.
+
+.. _quick-guide:
+
+Quick setup guide
+=================
+
+This guide will help you with the initial configuration of Powerline.
+
+Look at configuration in :file:`{powerline_root}/powerline/config_files`. If you 
+want to modify some file you can create :file:`~/.config/powerline` directory 
+and put modifications there: all configuration files are :ref:`merged 
+<configuration-merging>` with each other.
+
+Each extension (vim, tmux, etc.) has its own theme, and they are located in 
+:file:`{config directory}/themes/{extension}/default.json`. Best way to modify 
+it is to copy this theme as a whole, remove ``segment_data`` key with 
+corresponding value if present (unless you need to modify it, in which case only 
+modifications must be left) and do necessary modifications in the list of 
+segments (lists are not subject to merging: this is why you need a copy).
+
+If you want to move, remove or customize any of the provided segments in the 
+copy, you can do that by updating the segment dictionary in the theme you want 
+to customize. A segment dictionary looks like this:
+
+.. code-block:: javascript
+
+   {
+       "name": "segment_name"
+       ...
+   }
+
+You can move the segment dictionaries around to change the segment 
+positions, or remove the entire dictionary to remove the segment from the 
+prompt or statusline.
+
+.. note:: It’s essential that the contents of all your configuration files 
+   is valid JSON! It’s strongly recommended that you run your configuration 
+   files through ``jsonlint`` after changing them.
+
+.. note::
+   If your modifications appear not to work, run :ref:`powerline-lint script 
+   <command-powerline-lint>`. This script should show you the location of the 
+   error.
+
+Some segments need a user configuration to work properly. Here’s a couple of 
+segments that you may want to customize right away:
+
+**E-mail alert segment**
+    You have to set your username and password (and possibly server/port) 
+    for the e-mail alert segment. If you’re using GMail it’s recommended 
+    that you `generate an application-specific password 
+    <https://accounts.google.com/IssuedAuthSubTokens>`_ for this purpose.
+
+    Open a theme file, scroll down to the ``email_imap_alert`` segment and 
+    set your ``username`` and ``password``.  The server defaults to GMail’s 
+    IMAP server, but you can set the server/port by adding a ``server`` and 
+    a ``port`` argument.
+**Weather segment**
+    The weather segment will try to find your location using a GeoIP lookup, 
+    so unless you’re on a VPN you probably won’t have to change the location 
+    query.
+
+    It is using OpenWeatherMap as a provider, which can be configured with a
+    personal API key. These can be generated `here
+    <https://home.openweathermap.org/api_keys>`_
+
+    If you want to change the location query or the temperature unit you’ll 
+    have to update the segment arguments. Open a theme file, scroll down to 
+    the weather segment and update it to include unit, location query or
+    api key arguments:
+
+    .. code-block:: javascript
+
+       {
+           "name": "weather",
+           "priority": 50,
+           "args": {
+               "unit": "F",
+               "location_query": "oslo, norway",
+               "weather_api_key": "your_api_key"
+           }
+       },
+
+References
+==========
+
+.. toctree::
+   :glob:
+
+   configuration/reference
+   configuration/segments
+   configuration/listers
+   configuration/selectors
+   configuration/local
diff --git a/docs/source/configuration/listers.rst b/docs/source/configuration/listers.rst
new file mode 100644
index 0000000..7aaaabc
--- /dev/null
+++ b/docs/source/configuration/listers.rst
@@ -0,0 +1,35 @@
+.. _config-listers:
+
+****************
+Lister reference
+****************
+
+Listers are special segment collections which allow to show some list of 
+segments for each entity in the list of entities (multiply their segments list 
+by a list of entities). E.g. ``powerline.listers.vim.tablister`` presented with 
+``powerline.segments.vim.tabnr`` and ``….file_name`` as segments will emit 
+segments with buffer names and tabpage numbers for each tabpage shown by vim.
+
+Listers appear in configuration as irregular segments having ``segment_list`` as 
+their type and ``segments`` key with a list of segments (a bit more details in 
+:ref:`Themes section of configuration reference <config-themes-segments>`).
+
+More information in :ref:`Writing listers <dev-listers>` section.
+
+Vim listers
+-----------
+
+.. automodule:: powerline.listers.vim
+   :members:
+
+Pdb listers
+-----------
+
+.. automodule:: powerline.listers.pdb
+   :members:
+
+i3wm listers
+------------
+
+.. automodule:: powerline.listers.i3wm
+   :members:
diff --git a/docs/source/configuration/local.rst b/docs/source/configuration/local.rst
new file mode 100644
index 0000000..0f3d110
--- /dev/null
+++ b/docs/source/configuration/local.rst
@@ -0,0 +1,260 @@
+.. _local-configuration-overrides:
+
+*****************************
+Local configuration overrides
+*****************************
+
+Depending on the application used it is possible to override configuration. Here 
+is the list:
+
+Vim overrides
+=============
+
+Vim configuration can be overridden using the following options:
+
+.. _local-configuration-overrides-vim-config:
+
+``g:powerline_config_overrides``
+    Dictionary, recursively merged with contents of 
+    :file:`powerline/config.json`.
+
+``g:powerline_theme_overrides``
+    Dictionary mapping theme names to theme overrides, recursively merged with 
+    contents of :file:`powerline/themes/vim/{key}.json`. Note that this way some 
+    value (e.g. segment) in a list cannot be redefined, only the whole list 
+    itself: only dictionaries are merged recursively.
+
+``g:powerline_config_paths``
+    Paths list (each path must be expanded, ``~`` shortcut is not supported). 
+    Points to the list of directories which will be searched for configuration. 
+    When this option is present, none of the other locations are searched.
+
+``g:powerline_no_python_error``
+    If this variable is set to a true value it will prevent Powerline from reporting 
+    an error when loaded in a copy of vim without the necessary Python support.
+
+``g:powerline_use_var_handler``
+    This variable may be set to either 0 or 1. If it is set to 1 then Vim will 
+    save log in ``g:powerline_log_messages`` variable in addition to whatever 
+    was configured in :ref:`log_* options <config-common-log>`. Level is always 
+    :ref:`log_level <config-common-log_level>`, same for format.
+
+    .. warning::
+        This variable is deprecated. Use :ref:`log_file option 
+        <config-common-log>` in conjunction with 
+        :py:class:`powerline.vim.VimVarHandler` class and :ref:`Vim config 
+        overrides variable <local-configuration-overrides-vim-config>`. Using 
+        this is also the only variant to make saving into the environment 
+        variable the *only* place where log is saved or save into different 
+        variable.
+
+    .. autoclass:: powerline.vim.VimVarHandler
+
+.. _local-configuration-overrides-script:
+
+Powerline script overrides
+==========================
+
+Powerline script has a number of options controlling powerline behavior. Here 
+``VALUE`` always means “some JSON object”.
+
+``-c KEY.NESTED_KEY=VALUE`` or ``--config-override=KEY.NESTED_KEY=VALUE``
+    Overrides options from :file:`powerline/config.json`. 
+    ``KEY.KEY2.KEY3=VALUE`` is a shortcut for ``KEY={"KEY2": {"KEY3": VALUE}}``. 
+    Multiple options (i.e. ``-c K1=V1 -c K2=V2``) are allowed, result (in the 
+    example: ``{"K1": V1, "K2": V2}``) is recursively merged with the contents 
+    of the file.
+
+    If ``VALUE`` is omitted then corresponding key will be removed from the 
+    configuration (if it was present).
+
+``-t THEME_NAME.KEY.NESTED_KEY=VALUE`` or ``--theme-override=THEME_NAME.KEY.NESTED_KEY=VALUE``
+    Overrides options from :file:`powerline/themes/{ext}/{THEME_NAME}.json`. 
+    ``KEY.NESTED_KEY=VALUE`` is processed like described above, ``{ext}`` is the 
+    first argument to powerline script. May be passed multiple times.
+
+    If ``VALUE`` is omitted then corresponding key will be removed from the 
+    configuration (if it was present).
+
+``-p PATH`` or ``--config-path=PATH``
+    Sets directory where configuration should be read from. If present, no 
+    default locations are searched for configuration. No expansions are 
+    performed by powerline script itself, but ``-p ~/.powerline`` will likely be 
+    expanded by the shell to something like ``-p /home/user/.powerline``.
+
+.. warning::
+    Such overrides are suggested for testing purposes only. Use 
+    :ref:`Environment variables overrides <local-configuration-overrides-env>` 
+    for other purposes.
+
+.. _local-configuration-overrides-env:
+
+Environment variables overrides
+===============================
+
+All bindings that use ``POWERLINE_COMMAND`` environment variable support taking 
+overrides from environment variables. In this case overrides should look like 
+the following::
+
+    OVERRIDE='key1.key2.key3=value;key4.key5={"value":1};key6=true;key1.key7=10'
+
+. This will be parsed into
+
+.. code-block:: Python
+
+    {
+        "key1": {
+            "key2": {
+                "key3": "value"
+            },
+            "key7": 10,
+        },
+        "key4": {
+            "key5": {
+                "value": 1,
+            },
+        },
+        "key6": True,
+    }
+
+. Rules:
+
+#. Environment variable must form a semicolon-separated list of key-value pairs: 
+   ``key=value;key2=value2``.
+#. Keys are always dot-separated strings that must not contain equals sign (as 
+   well as semicolon) or start with an underscore. They are interpreted 
+   literally and create a nested set of dictionaries: ``k1.k2.k3`` creates 
+   ``{"k1":{"k2":{}}}`` and inside the innermost dictionary last key (``k3`` in 
+   the example) is contained with its value.
+#. Value may be empty in which case they are interpreted as an order to remove 
+   some value: ``k1.k2=`` will form ``{"k1":{"k2":REMOVE_THIS_KEY}}`` nested 
+   dictionary where ``k2`` value is a special value that tells 
+   dictionary-merging function to remove ``k2`` rather then replace it with 
+   something.
+#. Value may be a JSON strings like ``{"a":1}`` (JSON dictionary), ``["a",1]`` 
+   (JSON list), ``1`` or ``-1`` (JSON number), ``"abc"`` (JSON string) or 
+   ``true``, ``false`` and ``null`` (JSON boolean objects and ``Null`` object 
+   from JSON). General rule is that anything starting with a digit (U+0030 till 
+   U+0039, inclusive), a hyphenminus (U+002D), a quotation mark (U+0022), a left 
+   curly bracket (U+007B) or a left square bracket (U+005B) is considered to be 
+   some JSON object, same for *exact* values ``true``, ``false`` and ``null``.
+#. Any other value is considered to be literal string: ``k1=foo:bar`` parses to 
+   ``{"k1": "foo:bar"}``.
+
+The following environment variables may be used for overrides according to the 
+above rules:
+
+``POWERLINE_CONFIG_OVERRIDES``
+    Overrides values from :file:`powerline/config.json`.
+
+``POWERLINE_THEME_OVERRIDES``
+    Overrides values from :file:`powerline/themes/{ext}/{key}.json`. Top-level 
+    key is treated as a name of the theme for which overrides are used: e.g. to 
+    disable cwd segment defined in :file:`powerline/themes/shell/default.json` 
+    one needs to use::
+
+        POWERLINE_THEME_OVERRIDES=default.segment_data.cwd.display=false
+
+Additionally one environment variable is a usual *colon*-separated list of 
+directories: ``POWERLINE_CONFIG_PATHS``. This one defines paths which will be 
+searched for configuration. Empty paths in ``POWERLINE_CONFIG_PATHS`` are 
+ignored.
+
+.. note::
+    Overrides from environment variables have lower priority then 
+    :ref:`Powerline script overrides <local-configuration-overrides-script>`. 
+    Latter are suggested for tests only.
+
+Zsh/zpython overrides
+=====================
+
+Here overrides are controlled by similarly to the powerline script, but values 
+are taken from zsh variables. :ref:`Environment variable overrides 
+<local-configuration-overrides-env>` are also supported: if variable is a string 
+this variant is used.
+
+``POWERLINE_CONFIG_OVERRIDES``
+    Overrides options from :file:`powerline/config.json`. Should be a zsh 
+    associative array with keys equal to ``KEY.NESTED_KEY`` and values being 
+    JSON strings. Pair ``KEY.KEY1 VALUE`` is equivalent to ``{"KEY": {"KEY1": 
+    VALUE}}``. All pairs are then recursively merged into one dictionary and 
+    this dictionary is recursively merged with the contents of the file.
+
+``POWERLINE_THEME_OVERRIDES``
+    Overrides options from :file:`powerline/themes/shell/*.json`. Should be 
+    a zsh associative array with keys equal to ``THEME_NAME.KEY.NESTED_KEY`` and 
+    values being JSON strings. Is processed like the above 
+    ``POWERLINE_CONFIG_OVERRIDES``, but only subdictionaries for ``THEME_NAME`` 
+    key are merged with theme configuration when theme with given name is 
+    requested.
+
+``POWERLINE_CONFIG_PATHS``
+    Sets directories where configuration should be read from. If present, no 
+    default locations are searched for configuration. No expansions are 
+    performed by powerline script itself, but zsh usually performs them on its 
+    own if variable without is set without quotes: ``POWERLINE_CONFIG_PATHS=( 
+    ~/example )``. In addition to arrays usual colon-separated “array” string 
+    can be used: ``POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2``.
+
+Ipython overrides
+=================
+
+Ipython overrides depend on ipython version. Before ipython-0.11 additional 
+keyword arguments should be passed to setup() function. After ipython-0.11 
+``c.Powerline.KEY`` should be used. Supported ``KEY`` strings or keyword 
+argument names:
+
+``config_overrides``
+    Overrides options from :file:`powerline/config.json`. Should be a dictionary 
+    that will be recursively merged with the contents of the file.
+
+``theme_overrides``
+    Overrides options from :file:`powerline/themes/ipython/*.json`. Should be 
+    a dictionary where keys are theme names and values are dictionaries which 
+    will be recursively merged with the contents of the given theme.
+
+``config_paths``
+    Sets directories where configuration should be read from. If present, no 
+    default locations are searched for configuration. No expansions are 
+    performed thus paths starting with ``~/`` cannot be used: use 
+    :py:func:`os.path.expanduser`.
+
+Prompt command
+==============
+
+In addition to the above configuration options ``$POWERLINE_COMMAND`` 
+environment variable can be used to tell shell or tmux to use specific powerline 
+implementation and ``$POWERLINE_CONFIG_COMMAND`` to tell zsh or tmux where 
+``powerline-config`` script is located. This is mostly useful for putting 
+powerline into different directory.
+
+.. note::
+
+    ``$POWERLINE_COMMAND`` is always treated as one path in shell bindings, so 
+    path with spaces in it may be used. To specify additional arguments one may 
+    use ``$POWERLINE_COMMAND_ARGS``, but note that this variable exists for 
+    testing purposes only and may be removed. One should use :ref:`Environment 
+    variable overrides <local-configuration-overrides-env>` instead.
+
+To disable prompt in shell, but still have tmux support or to disable tmux 
+support environment variables ``$POWERLINE_NO_{SHELL}_PROMPT`` and 
+``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT`` can be used (substitute ``{SHELL}`` with 
+the name of the shell (all-caps) that should be affected (e.g. ``BASH``) or use 
+all-inclusive ``SHELL`` that will disable support for all shells). These 
+variables have no effect after configuration script was sourced (in fish case: 
+after ``powerline-setup`` function was run). To disable specific feature support 
+set one of these variables to some non-empty value.
+
+In order to keep shell prompt, but avoid launching Python twice to get unused 
+:ref:`above <config-themes-above>` lines in tcsh ``$POWERLINE_NO_TCSH_ABOVE`` or 
+``$POWERLINE_NO_SHELL_ABOVE`` variable should be set.
+
+In order to remove additional space from the end of the right prompt in fish 
+that was added in order to support multiline prompt ``$POWERLINE_NO_FISH_ABOVE`` 
+or ``$POWERLINE_NO_SHELL_ABOVE`` variable should be set.
+
+PDB overrides
+=============
+
+Like shell bindings :ref:`PDB bindings <pdb-prompt>` take overrides from 
+:ref:`environment variables <local-configuration-overrides-env>`.
diff --git a/docs/source/configuration/reference.rst b/docs/source/configuration/reference.rst
new file mode 100644
index 0000000..d4fd4ab
--- /dev/null
+++ b/docs/source/configuration/reference.rst
@@ -0,0 +1,602 @@
+***********************
+Configuration reference
+***********************
+
+.. _config-main:
+
+Main configuration
+==================
+
+:Location: :file:`powerline/config.json`
+
+The main configuration file defines some common options that applies to all 
+extensions, as well as some extension-specific options like themes and 
+colorschemes.
+
+Common configuration
+--------------------
+
+Common configuration is a subdictionary that is a value of ``common`` key in 
+:file:`powerline/config.json` file.
+
+.. _config-common-term_truecolor:
+
+``term_truecolor``
+    Defines whether to output cterm indices (8-bit) or RGB colors (24-bit) 
+    to the terminal emulator. See the :ref:`term-feature-support-matrix` for 
+    information on whether used terminal emulator supports 24-bit colors.
+
+    This variable is forced to be ``false`` if :ref:`term_escape_style 
+    <config-common-term_escape_style>` option is set to ``"fbterm"`` or if it is 
+    set to ``"auto"`` and powerline detected fbterm.
+
+.. _config-common-term_escape_style:
+
+``term_escape_style``
+    Defines what escapes sequences should be used. Accepts three variants:
+
+    =======  ===================================================================
+    Variant  Description
+    =======  ===================================================================
+    auto     ``xterm`` or ``fbterm`` depending on ``$TERM`` variable value: 
+             ``TERM=fbterm`` implies ``fbterm`` escaping style, all other values 
+             select ``xterm`` escaping.
+    xterm    Uses ``\e[{fb};5;{color}m`` for colors (``{fb}`` is either ``38`` 
+             (foreground) or ``48`` (background)). Should be used for most 
+             terminals.
+    fbterm   Uses ``\e[{fb};{color}}`` for colors (``{fb}`` is either ``1`` 
+             (foreground) or ``2`` (background)). Should be used for fbterm: 
+             framebuffer terminal.
+    =======  ===================================================================
+
+.. _config-common-ambiwidth:
+
+``ambiwidth``
+    Tells powerline what to do with characters with East Asian Width Class 
+    Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek
+    letters, Cyrillic letters). Valid values: any positive integer; it is 
+    suggested that this option is only set it to 1 (default) or 2.
+
+.. _config-common-watcher:
+
+``watcher``
+    Select filesystem watcher. Variants are
+
+    =======  ===================================
+    Variant  Description
+    =======  ===================================
+    auto     Selects most performant watcher.
+    inotify  Select inotify watcher. Linux only.
+    stat     Select stat-based polling watcher.
+    uv       Select libuv-based watcher.
+    =======  ===================================
+
+    Default is ``auto``.
+
+.. _config-common-additional_escapes:
+
+``additional_escapes``
+    Valid for shell extensions, makes sense only if :ref:`term_truecolor 
+    <config-common-term_truecolor>` is enabled. Is to be set from command-line. 
+    Controls additional escaping that is needed for tmux/screen to work with 
+    terminal true color escape codes: normally tmux/screen prevent terminal 
+    emulator from receiving these control codes thus rendering powerline prompt 
+    colorless. Valid values: ``"tmux"``, ``"screen"``, ``null`` (default).
+
+.. _config-common-paths:
+
+``paths``
+    Defines additional paths which will be searched for modules when using 
+    :ref:`function segment option <config-themes-seg-function>` or :ref:`Vim 
+    local_themes option <config-ext-local_themes>`. Paths defined here have 
+    priority when searching for modules.
+
+.. _config-common-log:
+
+``log_file``
+    Defines how logs will be handled. There are three variants here:
+
+    #. Absent. In this case logging will be done to stderr: equivalent to 
+       ``[["logging.StreamHandler", []]]`` or ``[null]``.
+    #. Plain string. In this case logging will be done to the given file: 
+       ``"/file/name"`` is equivalent to ``[["logging.FileHandler", 
+       [["/file/name"]]]]`` or ``["/file/name"]``. Leading ``~/`` is expanded in 
+       the file name, so using ``"~/.log/foo"`` is permitted. If directory 
+       pointed by the option is absent, it will be created, but not its parent.
+    #. List of handler definitions. Handler definition may either be ``null``, 
+       a string or a list with two or three elements:
+
+       #. Logging class name and module. If module name is absent, it is 
+          equivalent to ``logging.handlers``.
+       #. Class constructor arguments in a form ``[[args[, kwargs]]]``: accepted 
+          variants are ``[]`` (no arguments), ``[args]`` (e.g. 
+          ``[["/file/name"]]``: only positional arguments) or ``[args, kwargs]`` 
+          (e.g. ``[[], {"host": "localhost", "port": 6666}]``: positional and 
+          keyword arguments, but no positional arguments in the example).
+       #. Optional logging level. Overrides :ref:`log_level key 
+          <config-common-log_level>` and has the same format.
+       #. Optional format string. Partially overrides :ref:`log_format key 
+          <config-common-log_format>` and has the same format. “Partially” here 
+          means that it may only specify more critical level.
+
+.. _config-common-log_level:
+
+``log_level``
+    String, determines logging level. Defaults to ``WARNING``.
+
+.. _config-common-log_format:
+
+``log_format``
+    String, determines format of the log messages. Defaults to 
+    ``'%(asctime)s:%(level)s:%(message)s'``.
+
+``interval``
+    Number, determines time (in seconds) between checks for changed 
+    configuration. Checks are done in a separate thread. Use ``null`` to check 
+    for configuration changes on ``.render()`` call in main thread.
+    Defaults to ``None``.
+
+``reload_config``
+    Boolean, determines whether configuration should be reloaded at all. 
+    Defaults to ``True``.
+
+.. _config-common-default_top_theme:
+
+``default_top_theme``
+    String, determines which top-level theme will be used as the default. 
+    Defaults to ``powerline_terminus`` in unicode locales and ``ascii`` in 
+    non-unicode locales. See `Themes`_ section for more details.
+
+Extension-specific configuration
+--------------------------------
+
+Common configuration is a subdictionary that is a value of ``ext`` key in 
+:file:`powerline/config.json` file.
+
+``colorscheme``
+    Defines the colorscheme used for this extension.
+
+.. _config-ext-theme:
+
+``theme``
+    Defines the theme used for this extension.
+
+.. _config-ext-top_theme:
+
+``top_theme``
+    Defines the top-level theme used for this extension. See `Themes`_ section 
+    for more details.
+
+.. _config-ext-local_themes:
+
+``local_themes``
+    Defines themes used when certain conditions are met, e.g. for 
+    buffer-specific statuslines in vim. Value depends on extension used. For vim 
+    it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name`` 
+    is either ``matcher_module.module_attribute`` or ``module_attribute`` 
+    (``matcher_module`` defaults to ``powerline.matchers.vim``) and 
+    ``module_attribute`` should point to a function that returns boolean value 
+    indicating that current buffer has (not) matched conditions. There is an 
+    exception for ``matcher_name`` though: if it is ``__tabline__`` no functions 
+    are loaded. This special theme is used for ``tabline`` Vim option.
+
+    For shell and ipython it is a simple ``{prompt_type : theme_name}``, where 
+    ``prompt_type`` is a string with no special meaning (specifically it does 
+    not refer to any Python function). Shell has ``continuation``, and 
+    ``select`` prompts with rather self-explanatory names, IPython has ``in2``, 
+    ``out`` and ``rewrite`` prompts (refer to IPython documentation for more 
+    details) while ``in`` prompt is the default.
+
+    For wm (:ref:`lemonbar <lemonbar-usage>` only) it is a dictionary 
+    ``{output : theme_name}`` that maps the ``xrandr`` output names to the 
+    local themes to use on that output.
+
+.. _config-ext-components:
+
+``components``
+    Determines which extension components should be enabled. This key is highly 
+    extension-specific, here is the table of extensions and corresponding 
+    components:
+
+    +---------+----------+-----------------------------------------------------+
+    |Extension|Component |Description                                          |
+    +---------+----------+-----------------------------------------------------+
+    |vim      |statusline|Makes Vim use powerline statusline.                  |
+    |         +----------+-----------------------------------------------------+
+    |         |tabline   |Makes Vim use powerline tabline.                     |
+    +---------+----------+-----------------------------------------------------+
+    |shell    |prompt    |Makes shell display powerline prompt.                |
+    |         +----------+-----------------------------------------------------+
+    |         |tmux      |Makes shell report its current working directory     |
+    |         |          |and screen width to tmux for tmux powerline          |
+    |         |          |bindings.                                            |
+    |         |          |                                                     |
+    +---------+----------+-----------------------------------------------------+
+
+    All components are enabled by default.
+
+.. _config-ext-update_interval:
+
+``update_interval``
+    Determines how often WM status bars need to be updated, in seconds. Only 
+    valid for WM extensions which use ``powerline-daemon``. Defaults to 
+    2 seconds.
+
+.. _config-colors:
+
+Color definitions
+=================
+
+:Location: :file:`powerline/colors.json`
+
+.. _config-colors-colors:
+
+``colors``
+    Color definitions, consisting of a dict where the key is the name of the 
+    color, and the value is one of the following:
+
+    * A cterm color index.
+    * A list with a cterm color index and a hex color string (e.g. ``[123, 
+      "aabbcc"]``). This is useful for colorschemes that use colors that 
+      aren’t available in color terminals.
+
+``gradients``
+    Gradient definitions, consisting of a dict where the key is the name of the 
+    gradient, and the value is a list containing one or two items, second item 
+    is optional:
+
+    * A list of cterm color indices.
+    * A list of hex color strings.
+
+    It is expected that gradients are defined from least alert color to most 
+    alert or non-alert colors are used.
+
+.. _config-colorschemes:
+
+Colorschemes
+============
+
+:Location: :file:`powerline/colorschemes/{name}.json`, 
+           :file:`powerline/colorschemes/__main__.json`, 
+           :file:`powerline/colorschemes/{extension}/{name}.json`
+
+Colorscheme files are processed in order given: definitions from each next file 
+override those from each previous file. It is required that either 
+:file:`powerline/colorschemes/{name}.json`, or 
+:file:`powerline/colorschemes/{extension}/{name}.json` exists.
+
+``name``
+    Name of the colorscheme.
+
+.. _config-colorschemes-groups:
+
+``groups``
+    Segment highlighting groups, consisting of a dict where the key is the 
+    name of the highlighting group (usually the function name for function 
+    segments), and the value is either
+
+    #) a dict that defines the foreground color, background color and 
+       attributes:
+
+       ``fg``
+           Foreground color. Must be defined in :ref:`colors 
+           <config-colors-colors>`.
+
+       ``bg``
+           Background color. Must be defined in :ref:`colors 
+           <config-colors-colors>`.
+
+       ``attrs``
+           List of attributes. Valid values are one or more of ``bold``, 
+           ``italic`` and ``underline``. Note that some attributes may be 
+           unavailable in some applications or terminal emulators. If no 
+           attributes are needed this list should be left empty.
+
+    #) a string (an alias): a name of existing group. This group’s definition 
+       will be used when this color is requested.
+
+``mode_translations``
+    Mode-specific highlighting for extensions that support it (e.g. the vim 
+    extension). It’s an easy way of changing a color in a specific mode.  
+    Consists of a dict where the key is the mode and the value is a dict 
+    with the following options:
+
+    ``colors``
+        A dict where the key is the color to be translated in this mode, and 
+        the value is the new color. Both the key and the value must be defined 
+        in :ref:`colors <config-colors-colors>`.
+
+    ``groups``
+        Segment highlighting groups for this mode. Same syntax as the main 
+        :ref:`groups <config-colorschemes-groups>` option.
+
+.. _config-themes:
+
+Themes
+======
+
+:Location: :file:`powerline/themes/{top_theme}.json`, 
+           :file:`powerline/themes/{extension}/__main__.json`, 
+           :file:`powerline/themes/{extension}/{name}.json`
+
+Theme files are processed in order given: definitions from each next file 
+override those from each previous file. It is required that file 
+:file:`powerline/themes/{extension}/{name}.json` exists.
+
+`{top_theme}` component of the file name is obtained either from :ref:`top_theme 
+extension-specific key <config-ext-top_theme>` or from :ref:`default_top_theme 
+common configuration key <config-common-default_top_theme>`. Powerline ships 
+with the following top themes:
+
+.. _config-top_themes-list:
+
+==========================  ====================================================
+Theme                       Description
+==========================  ====================================================
+powerline                   Default powerline theme with fancy powerline symbols
+powerline_unicode7          Theme with powerline dividers and unicode-7 symbols
+unicode                     Theme without any symbols from private use area
+unicode_terminus            Theme containing only symbols from terminus PCF font
+unicode_terminus_condensed  Like above, but occupies as less space as possible
+powerline_terminus          Like unicode_terminus, but with powerline symbols
+ascii                       Theme without any unicode characters at all
+==========================  ====================================================
+
+``name``
+    Name of the theme.
+
+.. _config-themes-default_module:
+
+``default_module``
+    Python module where segments will be looked by default. Defaults to 
+    ``powerline.segments.{ext}``.
+
+``spaces``
+    Defines number of spaces just before the divider (on the right side) or just 
+    after it (on the left side). These spaces will not be added if divider is 
+    not drawn.
+
+``use_non_breaking_spaces``
+    Determines whether non-breaking spaces should be used in place of the 
+    regular ones. This option is needed because regular spaces are not displayed 
+    properly when using powerline with some font configuration. Defaults to 
+    ``True``.
+
+    .. note::
+       Unlike all other options this one is only checked once at startup using 
+       whatever theme is :ref:`the default <config-ext-theme>`. If this option 
+       is set in the local themes it will be ignored. This option may also be 
+       ignored in some bindings.
+
+``outer_padding``
+    Defines number of spaces at the end of output (on the right side) or at 
+    the start of output (on the left side). Defaults to ``1``.
+
+
+``dividers``
+    Defines the dividers used in all Powerline extensions.
+
+    The ``hard`` dividers are used to divide segments with different 
+    background colors, while the ``soft`` dividers are used to divide 
+    segments with the same background color.
+
+.. _config-themes-cursor_space:
+
+``cursor_space``
+    Space reserved for user input in shell bindings. It is measured in per 
+    cents.
+
+``cursor_columns``
+    Space reserved for user input in shell bindings. Unlike :ref:`cursor_space 
+    <config-themes-cursor_space>` it is measured in absolute amount of columns.
+
+.. _config-themes-segment_data:
+
+``segment_data``
+    A dict where keys are segment names or strings ``{module}.{function}``. Used 
+    to specify default values for various keys:
+    :ref:`after <config-themes-seg-after>`,
+    :ref:`before <config-themes-seg-before>`,
+    :ref:`contents <config-themes-seg-contents>` (only for string segments
+    if :ref:`name <config-themes-seg-name>` is defined),
+    :ref:`display <config-themes-seg-display>`.
+
+    Key :ref:`args <config-themes-seg-args>` (only for function and 
+    segment_list segments) is handled specially: unlike other values it is 
+    merged with all other values, except that a single ``{module}.{function}`` 
+    key if found prevents merging all ``{function}`` values.
+
+    When using :ref:`local themes <config-ext-local_themes>` values of these 
+    keys are first searched in the segment description, then in ``segment_data`` 
+    key of a local theme, then in ``segment_data`` key of a :ref:`default theme 
+    <config-ext-theme>`. For the :ref:`default theme <config-ext-theme>` itself 
+    step 2 is obviously avoided.
+
+    .. note:: Top-level themes are out of equation here: they are merged
+        before the above merging process happens.
+
+.. _config-themes-segments:
+
+``segments``
+    A dict with a ``left`` and a ``right`` lists, consisting of segment 
+    dictionaries. Shell themes may also contain ``above`` list of dictionaries. 
+    Each item in ``above`` list may have ``left`` and ``right`` keys like this 
+    dictionary, but no ``above`` key.
+
+    .. _config-themes-above:
+
+    ``above`` list is used for multiline shell configurations.
+
+    ``left`` and ``right`` lists are used for segments that should be put on the 
+    left or right side in the output. Actual mechanizm of putting segments on 
+    the left or the right depends on used renderer, but most renderers require 
+    one to specify segment with :ref:`width <config-themes-seg-width>` ``auto`` 
+    on either side to make generated line fill all of the available width.
+
+    Each segment dictionary has the following options:
+
+    .. _config-themes-seg-type:
+
+    ``type``
+        The segment type. Can be one of ``function`` (default), ``string`` or 
+        ``segment_list``:
+
+        ``function``
+            The segment contents is the return value of the function defined in 
+            the :ref:`function option <config-themes-seg-function>`.
+
+            List of function segments is available in :ref:`Segment reference 
+            <config-segments>` section.
+
+        ``string``
+            A static string segment where the contents is defined in the 
+            :ref:`contents option <config-themes-seg-contents>`, and the 
+            highlighting group is defined in the :ref:`highlight_groups option 
+            <config-themes-seg-highlight_groups>`.
+
+        ``segment_list``
+            Sub-list of segments. This list only allows :ref:`function 
+            <config-themes-seg-function>`, :ref:`segments 
+            <config-themes-seg-segments>` and :ref:`args 
+            <config-themes-seg-args>` options.
+
+            List of lister segments is available in :ref:`Lister reference 
+            <config-listers>` section.
+
+    .. _config-themes-seg-name:
+
+    ``name``
+        Segment name. If present allows referring to this segment in 
+        :ref:`segment_data <config-themes-segment_data>` dictionary by this 
+        name. If not ``string`` segments may not be referred there at all and 
+        ``function`` and ``segment_list`` segments may be referred there using 
+        either ``{module}.{function_name}`` or ``{function_name}``, whichever 
+        will be found first. Function name is taken from :ref:`function key 
+        <config-themes-seg-function>`.
+
+        .. note::
+            If present prevents ``function`` key from acting as a segment name.
+
+    .. _config-themes-seg-function:
+
+    ``function``
+        Function used to get segment contents, in format ``{module}.{function}`` 
+        or ``{function}``. If ``{module}`` is omitted :ref:`default_module 
+        option <config-themes-default_module>` is used.
+
+    .. _config-themes-seg-highlight_groups:
+
+    ``highlight_groups``
+        Highlighting group for this segment. Consists of a prioritized list of 
+        highlighting groups, where the first highlighting group that is 
+        available in the colorscheme is used.
+
+        Ignored for segments that have ``function`` type.
+
+    .. _config-themes-seg-before:
+
+    ``before``
+        A string which will be prepended to the segment contents.
+
+    .. _config-themes-seg-after:
+
+    ``after``
+        A string which will be appended to the segment contents.
+
+    .. _config-themes-seg-contents:
+
+    ``contents``
+        Segment contents, only required for ``string`` segments.
+
+    .. _config-themes-seg-args:
+
+    ``args``
+        A dict of arguments to be passed to a ``function`` segment.
+
+    .. _config-themes-seg-align:
+
+    ``align``
+        Aligns the segments contents to the left (``l``), center (``c``) or 
+        right (``r``). Has no sense if ``width`` key was not specified or if 
+        segment provides its own function for ``auto`` ``width`` handling and 
+        does not care about this option.
+
+    .. _config-themes-seg-width:
+
+    ``width``
+        Enforces a specific width for this segment.
+
+        This segment will work as a spacer if the width is set to ``auto``.
+        Several spacers may be used, and the space will be distributed 
+        equally among all the spacer segments. Spacers may have contents, 
+        either returned by a function or a static string, and the contents 
+        can be aligned with the ``align`` property.
+
+    .. _config-themes-seg-priority:
+
+    ``priority``
+        Optional segment priority. Segments with priority ``None`` (the default 
+        priority, represented by ``null`` in json) will always be included, 
+        regardless of the width of the prompt/statusline.
+
+        If the priority is any number, the segment may be removed if the 
+        prompt/statusline width is too small for all the segments to be 
+        rendered. A lower number means that the segment has a higher priority.
+
+        Segments are removed according to their priority, with low priority 
+        segments (i.e. with a greater priority number) being removed first.
+
+    .. _config-themes-seg-draw_divider:
+
+    ``draw_hard_divider``, ``draw_soft_divider``
+        Whether to draw a divider between this and the adjacent segment. The 
+        adjacent segment is to the *right* for segments on the *left* side, and 
+        vice versa. Hard dividers are used between segments with different 
+        background colors, soft ones are used between segments with same 
+        background. Both options default to ``True``.
+
+    .. _config-themes-seg-draw_inner_divider:
+
+    ``draw_inner_divider``
+        Determines whether inner soft dividers are to be drawn for function 
+        segments. Only applicable for functions returning multiple segments. 
+        Defaults to ``False``.
+
+    .. _config-themes-seg-exclude_modes:
+
+    ``exclude_modes``, ``include_modes``
+        A list of modes where this segment will be excluded: the segment is not 
+        included or is included in all modes, *except* for the modes in one of 
+        these lists respectively. If ``exclude_modes`` is not present then it 
+        acts like an empty list (segment is not excluded from any modes). 
+        Without ``include_modes`` it acts like a list with all possible modes 
+        (segment is included in all modes). When there are both 
+        ``exclude_modes`` overrides ``include_modes``.
+
+    .. _config-themes-seg-exclude_function:
+
+    ``exclude_function``, ``include_function``
+        Function name in a form ``{name}`` or ``{module}.{name}`` (in the first 
+        form ``{module}`` defaults to ``powerline.selectors.{ext}``). Determines 
+        under which condition specific segment will be included or excluded. By 
+        default segment is always included and never excluded. 
+        ``exclude_function`` overrides ``include_function``.
+
+        .. note::
+            Options :ref:`exclude_/include_modes 
+            <config-themes-seg-exclude_modes>` complement 
+            ``exclude_/include_functions``: segment will be included if it is 
+            included by either ``include_mode`` or ``include_function`` and will 
+            be excluded if it is excluded by either ``exclude_mode`` or 
+            ``exclude_function``.
+
+    .. _config-themes-seg-display:
+
+    ``display``
+        Boolean. If false disables displaying of the segment.
+        Defaults to ``True``.
+
+    .. _config-themes-seg-segments:
+
+    ``segments``
+        A list of subsegments.
diff --git a/docs/source/configuration/segments.rst b/docs/source/configuration/segments.rst
new file mode 100644
index 0000000..63b4975
--- /dev/null
+++ b/docs/source/configuration/segments.rst
@@ -0,0 +1,28 @@
+.. _config-segments:
+
+*****************
+Segment reference
+*****************
+
+Segments
+========
+
+Segments are written in Python, and the default segments provided with 
+Powerline are located in :file:`powerline/segments/{extension}.py`.  
+User-defined segments can be defined in any module in ``sys.path`` or 
+:ref:`paths common configuration option <config-common-paths>`, import is 
+always absolute.
+
+Segments are regular Python functions, and they may accept arguments. All 
+arguments should have a default value which will be used for themes that 
+don’t provide an ``args`` dict.
+
+More information is available in :ref:`Writing segments <dev-segments>` section.
+
+Available segments
+==================
+
+.. toctree::
+   :glob:
+
+   segments/*
diff --git a/docs/source/configuration/segments/common.rst b/docs/source/configuration/segments/common.rst
new file mode 100644
index 0000000..5d52d69
--- /dev/null
+++ b/docs/source/configuration/segments/common.rst
@@ -0,0 +1,57 @@
+***************
+Common segments
+***************
+
+VCS submodule
+=============
+
+.. automodule:: powerline.segments.common.vcs
+   :members:
+
+System properties
+=================
+
+.. automodule:: powerline.segments.common.sys
+   :members:
+
+Network
+=======
+
+.. automodule:: powerline.segments.common.net
+   :members:
+
+Current environment
+===================
+
+.. automodule:: powerline.segments.common.env
+   :members:
+
+Battery
+=======
+
+.. automodule:: powerline.segments.common.bat
+   :members:
+
+Weather
+=======
+
+.. automodule:: powerline.segments.common.wthr
+   :members:
+
+Date and time
+=============
+
+.. automodule:: powerline.segments.common.time
+   :members:
+
+Mail
+====
+
+.. automodule:: powerline.segments.common.mail
+   :members:
+
+Media players
+=============
+
+.. automodule:: powerline.segments.common.players
+   :members:
diff --git a/docs/source/configuration/segments/i3wm.rst b/docs/source/configuration/segments/i3wm.rst
new file mode 100644
index 0000000..d103374
--- /dev/null
+++ b/docs/source/configuration/segments/i3wm.rst
@@ -0,0 +1,6 @@
+*************
+i3wm segments
+*************
+
+.. automodule:: powerline.segments.i3wm
+   :members:
diff --git a/docs/source/configuration/segments/pdb.rst b/docs/source/configuration/segments/pdb.rst
new file mode 100644
index 0000000..b9a104b
--- /dev/null
+++ b/docs/source/configuration/segments/pdb.rst
@@ -0,0 +1,7 @@
+************
+PDB segments
+************
+
+.. automodule:: powerline.segments.pdb
+   :members:
+
diff --git a/docs/source/configuration/segments/shell.rst b/docs/source/configuration/segments/shell.rst
new file mode 100644
index 0000000..fb3c804
--- /dev/null
+++ b/docs/source/configuration/segments/shell.rst
@@ -0,0 +1,6 @@
+**************
+Shell segments
+**************
+
+.. automodule:: powerline.segments.shell
+   :members:
diff --git a/docs/source/configuration/segments/tmux.rst b/docs/source/configuration/segments/tmux.rst
new file mode 100644
index 0000000..1a4a78f
--- /dev/null
+++ b/docs/source/configuration/segments/tmux.rst
@@ -0,0 +1,6 @@
+*************
+Tmux segments
+*************
+
+.. automodule:: powerline.segments.tmux
+   :members:
diff --git a/docs/source/configuration/segments/vim.rst b/docs/source/configuration/segments/vim.rst
new file mode 100644
index 0000000..5df70d6
--- /dev/null
+++ b/docs/source/configuration/segments/vim.rst
@@ -0,0 +1,46 @@
+************
+Vim segments
+************
+
+.. automodule:: powerline.segments.vim
+   :members:
+
+
+Plugin-specific segments
+========================
+
+Asynchronous Linter Engine (ALE) segments
+-----------------------------------------
+
+.. automodule:: powerline.segments.vim.plugin.ale
+   :members:
+
+Syntastic segments
+------------------
+
+.. automodule:: powerline.segments.vim.plugin.syntastic
+   :members:
+
+Command-T segments
+------------------
+
+.. automodule:: powerline.segments.vim.plugin.commandt
+   :members:
+
+Tagbar segments
+---------------
+
+.. automodule:: powerline.segments.vim.plugin.tagbar
+   :members:
+
+NERDTree segments
+-----------------
+
+.. automodule:: powerline.segments.vim.plugin.nerdtree
+   :members:
+
+Capslock segments
+-----------------
+
+.. automodule:: powerline.segments.vim.plugin.capslock
+   :members:
diff --git a/docs/source/configuration/selectors.rst b/docs/source/configuration/selectors.rst
new file mode 100644
index 0000000..f9367b2
--- /dev/null
+++ b/docs/source/configuration/selectors.rst
@@ -0,0 +1,17 @@
+.. _config-selectors:
+
+******************
+Selector functions
+******************
+
+Selector functions are functions that return ``True`` or ``False`` depending on 
+application state. They are used for :ref:`exclude_function and include_function 
+segment options <config-themes-seg-exclude_function>`.
+
+Available selectors
+===================
+
+.. toctree::
+   :glob:
+
+   selectors/*
diff --git a/docs/source/configuration/selectors/vim.rst b/docs/source/configuration/selectors/vim.rst
new file mode 100644
index 0000000..5097320
--- /dev/null
+++ b/docs/source/configuration/selectors/vim.rst
@@ -0,0 +1,6 @@
+*************
+Vim selectors
+*************
+
+.. automodule:: powerline.selectors.vim
+   :members:
diff --git a/docs/source/develop.rst b/docs/source/develop.rst
new file mode 100644
index 0000000..bf45498
--- /dev/null
+++ b/docs/source/develop.rst
@@ -0,0 +1,13 @@
+***************
+Developer guide
+***************
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   develop/segments
+   develop/listers
+   develop/local-themes
+   develop/extensions
+   develop/tips-and-tricks
diff --git a/docs/source/develop/extensions.rst b/docs/source/develop/extensions.rst
new file mode 100644
index 0000000..2ddf223
--- /dev/null
+++ b/docs/source/develop/extensions.rst
@@ -0,0 +1,47 @@
+********************************
+Creating new powerline extension
+********************************
+
+Powerline extension is a code that tells powerline how to highlight and display 
+segments in some set of applications. Specifically this means
+
+#. Creating a :py:class:`powerline.Powerline` subclass that knows how to obtain 
+   :ref:`local configuration overrides <local-configuration-overrides>`. It also 
+   knows how to load local themes, but not when to apply them.
+
+   Instance of this class is the only instance that interacts directly with 
+   bindings code, so it has a proxy :py:meth:`powerline.Powerline.render` and 
+   :py:meth:`powerline.Powerline.shutdown` methods and other methods which may 
+   be useful for bindings.
+
+   This subclass must be placed directly in :file:`powerline` directory (e.g. in 
+   :file:`powerline/vim.py`) and named like ``VimPowerline`` (version of the 
+   file name without directory and extension and first capital letter 
+   + ``Powerline``). There is no technical reason for naming classes like this.
+#. Creating a :py:class:`powerline.renderer.Renderer` subclass that knows how to 
+   highlight a segment or reset highlighting to the default value (only makes 
+   sense in prompts). It is also responsible for selecting local themes and 
+   computing text width.
+
+   This subclass must be placed directly in :file:`powerline/renderers` 
+   directory (for powerline extensions developed for a set of applications use 
+   :file:`powerline/renderers/{ext}/*.py`) and named like ``ExtRenderer`` or 
+   ``AppPromptRenderer``. For technical reasons the class itself must be 
+   referenced in ``renderer`` module attribute thus allowing only one renderer 
+   per one module.
+#. Creating an extension bindings. These are to be placed in 
+   :file:`powerline/bindings/{ext}` and may contain virtually anything which may 
+   be required for powerline to work inside given applications, assuming it does 
+   not fit in other places.
+
+Powerline class
+===============
+
+.. autoclass:: powerline.Powerline
+   :members:
+
+Renderer class
+==============
+
+.. autoclass:: powerline.renderer.Renderer
+   :members:
diff --git a/docs/source/develop/listers.rst b/docs/source/develop/listers.rst
new file mode 100644
index 0000000..e779704
--- /dev/null
+++ b/docs/source/develop/listers.rst
@@ -0,0 +1,49 @@
+.. _dev-listers:
+
+***************
+Writing listers
+***************
+
+Listers provide a way to show some segments multiple times: once per each entity 
+(buffer, tabpage, etc) lister knows. They are functions which receive the 
+following arguments:
+
+``pl``
+    A :py:class:`powerline.PowerlineLogger` class instance. It must be used for 
+    logging.
+
+``segment_info``
+    Base segment info dictionary. Lister function or class must have 
+    ``powerline_requires_segment_info`` to receive this argument.
+
+    .. warning::
+        Listers are close to useless if they do not have access to this 
+        argument.
+
+    Refer to :ref:`segment_info detailed description <dev-segments-info>` for 
+    further details.
+
+``draw_inner_divider``
+    If False (default) soft dividers between segments in the listed group will 
+    not be drawn regardless of actual segment settings. If True they will be 
+    drawn, again regardless of actual segment settings. Set it to ``None`` in 
+    order to respect segment settings.
+
+And also any other argument(s) specified by user in :ref:`args key 
+<config-themes-seg-args>` (no additional arguments by default).
+
+Listers must return a sequence of pairs. First item in the pair must contain 
+a ``segment_info`` dictionary specific to one of the listed entities.
+
+Second item must contain another dictionary: it will be used to modify the 
+resulting segment. In addition to :ref:`usual keys that describe segment 
+<dev-segments-segment>` the following keys may be present (it is advised that 
+*only* the following keys will be used):
+
+``priority_multiplier``
+    Value (usually a ``float``) used to multiply segment priority. It is useful 
+    for finer-grained controlling which segments disappear first: e.g. when 
+    listing tab pages make first disappear directory names of the tabpages which 
+    are most far away from current tabpage, then (when all directory names 
+    disappeared) buffer names. Check out existing listers implementation in 
+    :file:`powerline/listers/vim.py`.
diff --git a/docs/source/develop/local-themes.rst b/docs/source/develop/local-themes.rst
new file mode 100644
index 0000000..959e1c4
--- /dev/null
+++ b/docs/source/develop/local-themes.rst
@@ -0,0 +1,59 @@
+************
+Local themes
+************
+
+From the user point of view local themes are the regular themes with a specific 
+scope where they are applied (i.e. specific vim window or specific kind of 
+prompt). Used themes are defined in :ref:`local_themes key 
+<config-ext-local_themes>`.
+
+Vim local themes
+================
+
+Vim is the only available extension that has a wide variaty of options for local 
+themes. It is the only extension where local theme key refers to a function as 
+described in :ref:`local_themes value documentation <config-ext-local_themes>`. 
+
+This function always takes a single value named ``matcher_info`` which is the 
+same dictionary as :ref:`segment_info dictionary <dev-segment_info-vim>`. Unlike 
+segments it takes this single argument as a *positional* argument, not as 
+a keyword one.
+
+Matcher function should return a boolean value: ``True`` if theme applies for 
+the given ``matcher_info`` dictionary or ``False`` if it is not. When one of the 
+matcher functions returns ``True`` powerline takes the corresponding theme at 
+uses it for the given window. Matchers are not tested in any particular order.
+
+In addition to :ref:`local_themes configuration key <config-ext-local_themes>` 
+developer of some plugin which wishes to support powerline without including his 
+code in powerline tree may use 
+:py:meth:`powerline.vim.VimPowerline.add_local_theme` method. It accepts two 
+arguments: matcher name (same as in :ref:`local_themes 
+<config-ext-local_themes>`) and dictionary with theme. This dictionary is merged 
+with :ref:`top theme <config-ext-top_theme>` and 
+:file:`powerline/themes/vim/__main__.json`. Note that if user already specified 
+the matcher in his configuration file ``KeyError`` is raised.
+
+Other local themes
+==================
+
+Except for Vim only IPython and shells have local themes. Unlike Vim these 
+themes are names with no special meaning (they do not refer to or cause loading 
+of any Python functions):
+
++---------+------------+-------------------------------------------------------+
+|Extension|Theme name  |Description                                            |
++---------+------------+-------------------------------------------------------+
+|Shell    |continuation|Shown for unfinished command (unclosed quote,          |
+|         |            |unfinished cycle).                                     |
+|         +------------+-------------------------------------------------------+
+|         |select      |Shown for ``select`` command available in some shells. |
++---------+------------+-------------------------------------------------------+
+|IPython  |in2         |Continuation prompt: shown for unfinished (multiline)  |
+|         |            |expression, unfinished class or function definition.   |
+|         +------------+-------------------------------------------------------+
+|         |out         |Displayed before the result.                           |
+|         +------------+-------------------------------------------------------+
+|         |rewrite     |Displayed before the actually executed code when       |
+|         |            |``autorewrite`` IPython feature is enabled.            |
++---------+------------+-------------------------------------------------------+
diff --git a/docs/source/develop/segments.rst b/docs/source/develop/segments.rst
new file mode 100644
index 0000000..59549f6
--- /dev/null
+++ b/docs/source/develop/segments.rst
@@ -0,0 +1,547 @@
+.. _dev-segments:
+
+****************
+Writing segments
+****************
+
+Each powerline segment is a callable object. It is supposed to be either 
+a Python function or :py:class:`powerline.segments.Segment` class. As a callable 
+object it should receive the following arguments:
+
+.. note:: All received arguments are keyword arguments.
+
+``pl``
+    A :py:class:`powerline.PowerlineLogger` instance. It must be used every time 
+    something needs to be logged.
+
+``segment_info``
+    A dictionary. It is only received if callable has 
+    ``powerline_requires_segment_info`` attribute.
+
+    Refer to :ref:`segment_info detailed description <dev-segments-info>` for 
+    further details.
+
+``create_watcher``
+    Function that will create filesystem watcher once called. Which watcher will 
+    be created exactly is controlled by :ref:`watcher configuration option 
+    <config-common-watcher>`.
+
+And also any other argument(s) specified by user in :ref:`args key 
+<config-themes-seg-args>` (no additional arguments by default).
+
+.. note::
+    For powerline-lint to work properly the following things may be needed:
+
+    #. If segment is a :py:class:`powerline.segments.Segment` instance and used 
+       arguments are scattered over multiple methods 
+       :py:meth:`powerline.segments.Segment.argspecobjs` should be overridden in 
+       subclass to tell powerline-lint which objects should be inspected for 
+       arguments.
+    #. If segment takes some arguments that are never listed, but accessed via 
+       ``kwargs.get()`` or previous function cannot be used for whatever reason 
+       :py:meth:`powerline.segments.Segment.additional_args` should be 
+       overridden in subclass.
+    #. If user is expected to use one :ref:`name <config-themes-seg-name>` for 
+       multiple segments which cannot be linked to the segment function 
+       automatically by powerline-lint (e.g. because there are no instances of 
+       the segments in question in the default configuration) 
+       :py:func:`powerline.lint.checks.register_common_name` function should be 
+       used.
+
+Object representing segment may have the following attributes used by 
+powerline:
+
+``powerline_requires_segment_info``
+    This attribute controls whether segment will receive ``segment_info`` 
+    argument: if it is present argument will be received.
+
+``powerline_requires_filesystem_watcher``
+    This attribute controls whether segment will receive ``create_watcher`` 
+    argument: if it is present argument will be received.
+
+``powerline_segment_datas``
+    This attribute must be a dictionary containing ``top_theme: segment_data`` 
+    mapping where ``top_theme`` is any theme name (it is expected that all of
+    the names from :ref:`top-level themes list <config-top_themes-list>` are 
+    present) and ``segment_data`` is a dictionary like the one that is contained 
+    inside :ref:`segment_data dictionary in configuration 
+    <config-themes-segment_data>`. This attribute should be used to specify 
+    default theme-specific values for *third-party* segments: powerline 
+    theme-specific values go directly to :ref:`top-level themes 
+    <config-themes>`.
+
+.. _dev-segments-startup:
+
+``startup``
+    This attribute must be a callable which accepts the following keyword 
+    arguments:
+
+    * ``pl``: :py:class:`powerline.PowerlineLogger` instance which is to be used 
+      for logging.
+    * ``shutdown_event``: :py:class:`Event` object which will be set when 
+      powerline will be shut down.
+    * Any arguments found in user configuration for the given segment (i.e. 
+      :ref:`args key <config-themes-seg-args>`).
+
+    This function is called at powerline startup when using long-running 
+    processes (e.g. powerline in vim, in zsh with libzpython, in ipython or in 
+    powerline daemon) and not called when ``powerline-render`` executable is 
+    used (more specific: when :py:class:`powerline.Powerline` constructor 
+    received true ``run_once`` argument).
+
+.. _dev-segments-shutdown:
+
+``shutdown``
+    This attribute must be a callable that accepts no arguments and shuts down 
+    threads and frees any other resources allocated in ``startup`` method of the 
+    segment in question.
+
+    This function is not called when ``startup`` method is not called.
+
+.. _dev-segments-expand:
+
+``expand``
+    This attribute must be a callable that accepts the following keyword 
+    arguments:
+
+    * ``pl``: :py:class:`powerline.PowerlineLogger` instance which is to be used 
+      for logging.
+    * ``amount``: integer number representing amount of display cells result 
+      must occupy.
+
+      .. warning::
+         “Amount of display cells” is *not* number of Unicode codepoints, string 
+         length, or byte count. It is suggested that this function should look 
+         something like ``return (' ' * amount) + segment['contents']`` where 
+         ``' '`` may be replaced with anything that is known to occupy exactly 
+         one display cell.
+    * ``segment``: :ref:`segment dictionary <dev-segments-segment>`.
+    * Any arguments found in user configuration for the given segment (i.e. 
+      :ref:`args key <config-themes-seg-args>`).
+
+    It must return new value of :ref:`contents <dev-segments-seg-contents>` key.
+
+.. _dev-segments-truncate:
+
+``truncate``
+    Like :ref:`expand function <dev-segments-expand>`, but for truncating 
+    segments. Here ``amount`` means the number of display cells which must be 
+    freed.
+
+    This function is called for all segments before powerline starts purging 
+    them to free space.
+
+This callable object should may return either a string (``unicode`` in Python2 
+or ``str`` in Python3, *not* ``str`` in Python2 or ``bytes`` in Python3) object 
+or a list of dictionaries. String object is a short form of the following return 
+value:
+
+.. code-block:: python
+
+    [{
+        'contents': original_return,
+        'highlight_groups': [segment_name],
+    }]
+
+.. _dev-segments-return:
+
+Returned list is a list of segments treated independently, except for 
+:ref:`draw_inner_divider key <dev-segments-draw_inner_divider>`.
+
+All keys in segments returned by the function override those obtained from 
+:ref:`configuration <config-themes-segments>` and have the same meaning.
+
+Detailed description of used dictionary keys:
+
+.. _dev-segments-contents:
+
+``contents``
+    Text displayed by segment. Should be a ``unicode`` (Python2) or ``str`` 
+    (Python3) instance.
+
+``literal_contents``
+    Text that needs to be output literally (i.e. without passing through 
+    :py:meth:`powerline.renderer.strwidth` to determine length, through
+    :py:meth:`powerline.renderer.escape` to escape special characters and 
+    through :py:meth:`powerline.renderer.hl` to highlight it). Should be a tuple
+    ``(contents_length, contents)`` where ``contents_length`` is an integer and 
+    ``contents`` is a ``unicode`` (Python2) or ``str`` (Python3) instance.
+
+    If this key is present and its second value is true then other contents keys 
+    (:ref:`contents <dev-segments-contents>`, :ref:`after
+    <config-themes-seg-after>`, :ref:`before <config-themes-seg-before>`) will 
+    be ignored.
+
+    .. note::
+       If target is inclusion of the segment in powerline upstream all segment 
+       functions that output *only* subsegments with ``literal_contents`` key
+       must contain the following string in documentation::
+
+           No highlight groups are used (literal segment).
+
+       String must be present on the separate line.
+
+.. _dev-segments-draw_inner_divider:
+
+``draw_hard_divider``, ``draw_soft_divider``, ``draw_inner_divider``
+    Determines whether given divider should be drawn. All have the same meaning 
+    as :ref:`the similar keys in configuration <config-themes-seg-draw_divider>` 
+    (:ref:`draw_inner_divider <config-themes-seg-draw_inner_divider>`).
+
+.. _dev-segments-highlight_groups:
+
+``highlight_groups``
+    Determines segment highlighting. Refer to :ref:`themes documentation 
+    <config-themes-seg-highlight_groups>` for more details.
+
+    Defaults to the name of the segment.
+
+    .. note::
+       If target is inclusion of the segment in powerline upstream all used 
+       highlighting groups must be specified in the segment documentation in the 
+       form::
+
+           Highlight groups used: ``g1``[ or ``g2``]*[, ``g3`` (gradient)[ or ``g4``]*]*.
+
+       I.e. use::
+
+           Highlight groups used: ``foo_gradient`` (gradient) or ``foo``, ``bar``.
+
+       to specify that the segment uses *either* ``foo_gradient`` group or 
+       ``foo`` group *and* ``bar`` group meaning that ``powerline-lint`` will 
+       check that at least one of the first two groups is defined (and if 
+       ``foo_gradient`` is defined it must use at least one gradient color) and 
+       third group is defined as well.
+
+       All groups must be specified on one line.
+
+``divider_highlight_group``
+    Determines segment divider highlight group. Only applicable for soft 
+    dividers: colors for hard dividers are determined by colors of adjacent 
+    segments.
+
+    .. note::
+       If target is inclusion of the segment in powerline upstream used divider 
+       highlight group must be specified in the segment documentation in the 
+       form::
+
+            Divider highlight group used: ``group``.
+
+        This text must not wrap and all divider highlight group names are 
+        supposed to end with ``:divider``: e.g. ``cwd:divider``.
+
+``gradient_level``
+    First and the only key that may not be specified in user configuration. It 
+    determines which color should be used for this segment when one of the 
+    highlighting groups specified by :ref:`highlight_groups 
+    <dev-segments-highlight_groups>` was defined to use the color gradient.
+
+    This key may have any value from 0 to 100 inclusive, value is supposed to be 
+    an ``int`` or ``float`` instance.
+
+    No error occurs if segment has this key, but no used highlight groups use 
+    gradient color.
+
+``_*``
+    Keys starting with underscore are reserved for powerline and must not be 
+    returned.
+
+``__*``
+    Keys starting with two underscores are reserved for the segment functions, 
+    specifically for :ref:`expand function <dev-segments-expand>`.
+
+.. _dev-segments-segment:
+
+Segment dictionary
+==================
+
+Segment dictionary contains the following keys:
+
+* All keys returned by segment function (if it was used).
+
+* All of the following keys:
+
+  ``name``
+    Segment name: value of the :ref:`name key <config-themes-seg-name>` or 
+    function name (last component of the :ref:`function key 
+    <config-themes-seg-function>`). May be ``None``.
+
+  ``type``
+    :ref:`Segment type <config-themes-seg-type>`. Always represents actual type 
+    and is never ``None``.
+
+  ``highlight_groups``, ``divider_highlight_group``
+    Used highlight groups. May be ``None``.
+
+  ``highlight_group_prefix``
+    If this key is present then given prefix will be prepended to each highlight 
+    group (both regular and divider) used by this segment in a form 
+    ``{prefix}:{group}`` (note the colon). This key is mostly useful for 
+    :ref:`segment listers <dev-listers>`.
+
+  .. _dev-segments-seg-around:
+
+  ``before``, ``after``
+    Value of :ref:`before <config-themes-seg-before>` or :ref:`after 
+    <config-themes-seg-after>` configuration options. May be ``None`` as well as 
+    an empty string.
+
+  ``contents_func``
+    Function used to get segment contents. May be ``None``.
+
+  .. _dev-segments-seg-contents:
+
+  ``contents``
+    Actual segment contents, excluding dividers and :ref:`before/after 
+    <dev-segments-seg-around>`. May be ``None``.
+
+  ``priority``
+    :ref:`Segment priority <config-themes-seg-priority>`. May be ``None`` for no 
+    priority (such segments are always shown).
+
+  ``draw_soft_divider``, ``draw_hard_divider``, ``draw_inner_divider``
+    :ref:`Divider control flags <dev-segments-draw_inner_divider>`.
+
+  ``side``
+    Segment side: ``right`` or ``left``.
+
+  ``display_condition``
+    Contains function that takes three position parameters: 
+    :py:class:`powerline.PowerlineLogger` instance, :ref:`segment_info 
+    <dev-segments-info>` dictionary and current mode and returns either ``True`` 
+    or ``False`` to indicate whether particular segment should be processed.
+
+    This key is constructed based on :ref:`exclude_/include_modes keys 
+    <config-themes-seg-exclude_modes>` and :ref:`exclude_/include_function keys 
+    <config-themes-seg-exclude_function>`.
+
+  ``width``, ``align``
+    :ref:`Width and align options <config-themes-seg-align>`. May be ``None``.
+
+  ``expand``, ``truncate``
+    Partially applied :ref:`expand <dev-segments-expand>` or :ref:`truncate 
+    <dev-segments-truncate>` function. Accepts ``pl``, ``amount`` and 
+    ``segment`` positional parameters, keyword parameters from :ref:`args 
+    <config-themes-seg-args>` key were applied.
+
+  ``startup``
+    Partially applied :ref:`startup function <dev-segments-startup>`. Accepts 
+    ``pl`` and ``shutdown_event`` positional parameters, keyword parameters from 
+    :ref:`args <config-themes-seg-args>` key were applied.
+
+  ``shutdown``
+    :ref:`Shutdown function <dev-segments-shutdown>`. Accepts no argument.
+
+Segments layout
+===============
+
+Powerline segments are all located in one of the ``powerline.segments`` 
+submodules. For extension-specific segments ``powerline.segments.{ext}`` module 
+should be used (e.g. ``powerline.segments.shell``), for extension-agnostic there 
+is ``powerline.segments.common``.
+
+Plugin-specific segments (currently only those that are specific to vim plugins) 
+should live in ``powerline.segments.{ext}.plugin.{plugin_name}``: e.g. 
+``powerline.segments.vim.plugin.gundo``.
+
+.. _dev-segments-info:
+
+Segment information used in various extensions
+==============================================
+
+Each ``segment_info`` value should be a dictionary with at least the following 
+keys:
+
+``environ``
+    Current environment, may be an alias to ``os.environ``. Is guaranteed to 
+    have ``__getitem__`` and ``get`` methods and nothing more.
+
+    .. warning::
+       ``os.environ`` must not ever be used:
+
+       * If segment is run in the daemon this way it will get daemon’s 
+         environment which is not correct.
+       * If segment is run in Vim or in zsh with libzpython ``os.environ`` will 
+         contain Vim or zsh environ *at the moment Python interpreter was 
+         loaded*.
+
+``getcwd``
+    Function that returns current working directory being called with no 
+    arguments. ``os.getcwd`` must not be used for the same reasons the use of 
+    ``os.environ`` is forbidden, except that current working directory is valid 
+    in Vim and zsh (but not in daemon).
+
+``home``
+    Current home directory. May be false.
+
+.. _dev-segment_info-vim:
+
+Vim
+---
+
+Vim ``segment_info`` argument is a dictionary with the following keys:
+
+``window``
+    ``vim.Window`` object. ``vim.current.window`` or ``vim.windows[number - 1]`` 
+    may be used to obtain such object. May be a false object, in which case any 
+    of this object’s properties must not be used.
+
+``winnr``
+    Window number. Same as ``segment_info['window'].number`` *assuming* Vim is 
+    new enough for ``vim.Window`` object to have ``number`` attribute.
+
+``window_id``
+    Internal powerline window id, unique for each newly created window. It is 
+    safe to assume that this ID is hashable and supports equality comparison, 
+    but no other assumptions about it should be used. Currently uses integer 
+    numbers incremented each time window is created.
+
+``buffer``
+    ``vim.Buffer`` object. One may be obtained using ``vim.current.buffer``, 
+    ``segment_info['window'].buffer`` or ``vim.buffers[some_number]``. Note that 
+    in the latter case depending on vim version ``some_number`` may be ``bufnr`` 
+    or the internal Vim buffer index which is *not* buffer number. For this 
+    reason to get ``vim.Buffer`` object other then stored in ``segment_info`` 
+    dictionary iteration over ``vim.buffers`` and checking their ``number`` 
+    attributes should be performed.
+
+``bufnr``
+    Buffer number.
+
+``tabpage``
+    ``vim.Tabpage`` object. One may be obtained using ``vim.current.tabpage`` or 
+    ``vim.tabpages[number - 1]``. May be a false object, in which case no 
+    object’s properties can be used.
+
+``tabnr``
+    Tabpage number.
+
+``mode``
+    Current mode.
+
+``encoding``
+    Value of ``&encoding`` from the time when powerline was initialized. It 
+    should be used to convert return values.
+
+.. note::
+   Segment generally should not assume that it is run for the current window, 
+   current buffer or current tabpage. “Current window” and “current buffer” 
+   restrictions may be ignored if ``window_cached`` decorator is used, “current 
+   tabpage” restriction may be safely ignored if segment is not supposed to be 
+   used in tabline.
+
+.. warning::
+   Powerline is being tested with vim-7.0.112 (some minor sanity check) and 
+   latest Vim. This means that most of the functionality like 
+   ``vim.Window.number``, ``vim.*.vars``, ``vim.*.options`` or even ``dir(vim 
+   object)`` should be avoided in segments that want to be included in the 
+   upstream.
+
+Shell
+-----
+
+``args``
+    Parsed shell arguments: a ``argparse.Namespace`` object. Check out 
+    ``powerline-render --help`` for the list of all available arguments. 
+    Currently it is expected to contain at least the following attributes:
+
+    ``last_exit_code``
+        Exit code returned by last shell command. Is either one integer, 
+        ``sig{name}`` or ``sig{name}+core`` (latter two are only seen in ``rc`` 
+        shell).
+
+    ``last_pipe_status``
+        List of exit codes returned by last programs in the pipe or some false 
+        object. Only available in ``zsh`` and ``rc``. Is a list of either 
+        integers, ``sig{name}`` or ``sig{name}+core`` (latter two are only seen 
+        in ``rc`` shell).
+
+    ``jobnum``
+        Number of background jobs.
+
+    ``renderer_arg``
+        Dictionary containing some keys that are additional arguments used by 
+        shell bindings. *This attribute must not be used directly*: all 
+        arguments from this dictionary are merged with ``segment_info`` 
+        dictionary. Known to have at least the following keys:
+
+        ``client_id``
+            Identifier unique to one shell instance. Is used to record instance 
+            state by powerline daemon. In tmux this is the same as :ref:`pane_id 
+            <dev-seginfo-shell-renarg-pane_id>`.
+
+            It is not guaranteed that existing client ID will not be retaken 
+            when old shell with this ID quit: usually process PID is used as 
+            a client ID.
+
+            It is also not guaranteed that client ID will be process PID, number 
+            or something else at all. It is guaranteed though that client ID 
+            will be some hashable object which supports equality comparison.
+
+        ``local_theme``
+            Local theme that will be used by shell. One should not rely on the 
+            existence of this key.
+
+        .. _dev-seginfo-shell-renarg-pane_id:
+
+        ``pane_id``
+            Identifier unique to each tmux pane. Is always an integer, optional. 
+            Obtained by using ``tmux display -p '#D'``, then all leading spaces 
+            and per cent signs are stripped and the result is converted into an 
+            integer.
+
+        Other keys, if any, are specific to segments.
+
+Ipython
+-------
+
+``ipython``
+    Some object which has ``prompt_count`` attribute. Currently it is guaranteed 
+    to have only this attribute.
+
+    Attribute ``prompt_count`` contains the so-called “history count” 
+    (equivalent to ``\N`` in ``in_template``).
+
+Pdb
+---
+
+``pdb``
+    Currently active :py:class:`pdb.Pdb` instance.
+
+``curframe``
+    Frame which will be run next. Note: due to the existence of 
+    :py:func:`powerline.listers.pdb.frame_lister` one must not use 
+    ``segment_info['pdb'].curframe``.
+
+``initial_stack_length``
+    Equal to the length of :py:attr:`pdb.Pdb.stack` at the first invocation of 
+    the prompt decremented by one.
+
+i3wm
+----
+
+``mode``
+    Currently active i3 mode (as a string).
+
+``output``
+    ``xrandr`` output name currently drawing to. Currently only available
+    in lemonbar bindings.
+
+``workspace``
+	   the `i3-ipc` workspace object corresponding to this workspace.
+	   Contains string attributes ``name`` and ``output``, as well as boolean
+	   attributes for ``visible``, ``urgent`` and ``focused``. Currently only
+    provided by  the :py:func:`powerline.listers.i3wm.workspace_lister` lister.
+
+Segment class
+=============
+
+.. autoclass:: powerline.segments.Segment
+   :members:
+
+PowerlineLogger class
+=====================
+
+.. autoclass:: powerline.PowerlineLogger
+   :members:
+   :undoc-members:
diff --git a/docs/source/develop/tips-and-tricks.rst b/docs/source/develop/tips-and-tricks.rst
new file mode 100644
index 0000000..c850659
--- /dev/null
+++ b/docs/source/develop/tips-and-tricks.rst
@@ -0,0 +1,21 @@
+****************************************
+Tips and tricks for powerline developers
+****************************************
+
+Profiling powerline in Vim
+==========================
+
+Given that current directory is the root of the powerline repository the 
+following command may be used:
+
+.. code-block:: sh
+
+    vim --cmd 'let g:powerline_pyeval="powerline#debug#profile_pyeval"' \
+        --cmd 'set rtp=powerline/bindings/vim' \
+        -c 'runtime! plugin/powerline.vim' \
+        {other arguments if needed}
+
+After some time run ``:WriteProfiling {filename}`` Vim command. Currently this 
+only works with recent Vim and python-2*. It should be easy to modify 
+:file:`powerline/bindings/vim/autoload/powerline/debug.vim` to suit other 
+needs.
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..9a4d84b
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,28 @@
+*********
+Powerline
+*********
+
+.. toctree::
+   :maxdepth: 3
+   :glob:
+
+   overview
+   installation
+   usage
+   configuration
+   develop
+   troubleshooting
+   tips-and-tricks
+   license-and-credits
+
+.. toctree::
+   :maxdepth: 2
+
+   commands
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..8dc4236
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,131 @@
+************
+Installation
+************
+
+Generic requirements
+====================
+
+* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later, PyPy3 2.3 or later. It 
+  is the only non-optional requirement.
+
+  .. warning:
+     It is highly advised to use UCS-4 version of Python because UCS-2 version 
+     uses significantly slower text processing (length determination and 
+     non-printable character replacement) functions due to the need of 
+     supporting unicode characters above U+FFFF which are represented as 
+     surrogate pairs. This price will be paid even if configuration has no such 
+     characters.
+
+* C compiler. Required to build powerline client on linux. If it is not present 
+  then powerline will fall back to shell script or python client.
+* ``socat`` program. Required for shell variant of client which runs a bit 
+  faster than python version of the client, but still slower than C version.
+* ``psutil`` python package. Required for some segments like cpu_percent. Some 
+  segments have linux-only fallbacks for ``psutil`` functionality.
+* ``hglib`` python package *and* mercurial executable. Required to work with
+  mercurial repositories.
+* ``pygit2`` python package or ``git`` executable. Required to work with ``git`` 
+  repositories.
+* ``bzr`` python package (note: *not* standalone executable). Required to work 
+  with bazaar repositories.
+* ``pyuv`` python package. Required for :ref:`libuv-based watcher 
+  <config-common-watcher>` to work.
+* ``i3ipc`` python package. Required for i3wm bindings and segments.
+* ``xrandr`` program. Required for the multi-monitor lemonbar binding and the 
+  :py:func:`powerline.listers.i3wm.output_lister`.
+
+.. note::
+    Until bazaar supports Python-3 or PyPy powerline will not support
+    repository information when running in these interpreters.
+
+.. _repository-root:
+
+.. note::
+   When using ``pip``, the ``{repository_root}`` directory referenced in 
+   documentation may be found using ``pip show powerline-status``. In the output 
+   of ``pip show`` there is a line like ``Location: {path}``, that ``{path}`` is 
+   ``{repository_root}``. Unless it is ``--editable`` installation this is only 
+   applicable for ``{repository_root}/powerline/…`` paths: something like 
+   ``{repository_root}/scripts/powerline-render`` is not present.
+
+   When using other packages referenced paths may not exist, in this case refer 
+   to package documentation.
+
+Pip installation
+================
+
+Due to a naming conflict with an unrelated project, powerline is available on 
+PyPI under the ``powerline-status`` name:
+
+.. code-block:: sh
+
+    pip install powerline-status
+
+is the preferred method because this will get the latest release. To get current 
+development version
+
+.. code-block:: sh
+
+    pip install --user git+https://github.com/powerline/powerline
+
+may be used. If powerline was already checked out into some directory
+
+.. code-block:: sh
+
+    pip install --user --editable={path_to_powerline}
+
+is useful, but note that in this case ``pip`` will not install ``powerline`` 
+executable and something like
+
+.. code-block:: sh
+
+    ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
+
+will have to be done (:file:`~/.local/bin` should be replaced with some path 
+present in ``$PATH``).
+
+.. note::
+    We can use either ``https``(``git+ssh://git@github.com/powerline/powerline``)
+    or ``https``(``git+https://github.com/powerline/powerline``) protocols.
+    ``git`` protocol is deprecated by Github.
+
+Fonts installation
+==================
+
+Powerline uses several special glyphs to get the arrow effect and some custom 
+symbols for developers. This requires having either a symbol font or a patched 
+font installed in the system. The used application (e.g. terminal emulator) must 
+also either be configured to use patched fonts (in some cases even support it 
+because custom glyphs live in private use area which some applications reserve 
+for themselves) or support fontconfig for powerline to work properly with 
+powerline-specific glyphs.
+
+:ref:`24-bit color support <config-common-term_truecolor>` may be enabled if 
+used terminal emulator supports it (see :ref:`the terminal emulator support 
+matrix <usage-terminal-emulators>`).
+
+There are basically two ways to get powerline glyphs displayed: use 
+:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or 
+install a patched font.
+
+.. _installation-patched-fonts:
+
+Patched fonts
+-------------
+
+This method is the fallback method and works for every terminal.
+
+Download the font from `powerline-fonts`_. If preferred font can’t be found in 
+the `powerline-fonts`_ repo, then patching the preferred font is needed instead.
+
+.. _powerline-fonts: https://github.com/powerline/fonts
+
+After downloading this font refer to platform-specific instructions.
+
+Installation on various platforms
+=================================
+
+.. toctree::
+
+   Linux <installation/linux>
+   OS X <installation/osx>
diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst
new file mode 100644
index 0000000..e134707
--- /dev/null
+++ b/docs/source/installation/linux.rst
@@ -0,0 +1,110 @@
+*********************
+Installation on Linux
+*********************
+
+The following distribution-specific packages are officially supported, and they 
+provide an easy way of installing and upgrading Powerline. The packages will 
+automatically do most of the configuration.
+
+* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_
+* `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
+* Gentoo Live ebuild in `raiagent <https://github.com/leycec/raiagent>`_ overlay
+* Powerline package is available for Debian starting from Wheezy (via `backports 
+  <https://packages.debian.org/wheezy-backports/powerline>`_). Use `search 
+  <https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all&section=all>`_ 
+  to get more information.
+
+If used distribution does not have an official package installation guide below 
+should be followed:
+
+1. Install Python 3.2+, Python 2.6+ or PyPy and ``pip`` with ``setuptools``. 
+   This step is distribution-specific, so no commands provided.
+2. Install Powerline using one of the following commands:
+
+   .. code-block:: sh
+
+      pip install --user powerline-status
+
+   will get the latest release version and
+
+   .. code-block:: sh
+
+      pip install --user git+https://github.com/powerline/powerline
+
+   will get the latest development version.
+
+   .. note:: Due to the naming conflict with an unrelated project powerline is
+      named ``powerline-status`` in PyPI.
+
+   .. note::
+      Powerline developers should be aware that``pip install --editable`` does 
+      not currently fully work. Installation performed this way are missing 
+      ``powerline`` executable that needs to be symlinked. It will be located in 
+      ``scripts/powerline``.
+
+Fonts installation
+==================
+
+Fontconfig
+----------
+
+This method only works on Linux. It’s the second recommended method if terminal 
+emulator supports it as patching fonts is not needed, and it generally works 
+with any coding font.
+
+#. Download the latest version of the symbol font and fontconfig file::
+
+      wget https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf
+      wget https://github.com/powerline/powerline/raw/develop/font/10-powerline-symbols.conf
+
+#. Move the symbol font to a valid X font path. Valid font paths can be 
+   listed with ``xset q``::
+
+      mv PowerlineSymbols.otf ~/.local/share/fonts/
+
+#. Update font cache for the path the font was moved to (root privileges may be 
+   needed to update cache for the system-wide paths)::
+
+      fc-cache -vf ~/.local/share/fonts/
+
+#. Install the fontconfig file. For newer versions of fontconfig the config 
+   path is ``~/.config/fontconfig/conf.d/``, for older versions it’s  
+   ``~/.fonts.conf.d/``::
+
+      mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
+
+If custom symbols still cannot be seen then try closing all instances of the 
+terminal emulator. Restarting X may be needed for the changes to take effect.
+
+If custom symbols *still* can’t be seen, double-check that the font have been 
+installed to a valid X font path, and that the fontconfig file was installed to 
+a valid fontconfig path. Alternatively try to install a :ref:`patched font 
+<installation-patched-fonts>`.
+
+Patched font installation
+-------------------------
+
+This is the preferred method, but it is not always available because not all 
+fonts were patched and not all fonts *can* be patched due to licensing issues.
+
+After downloading font the following should be done:
+
+#. Move the patched font to a valid X font path. Valid font paths can be 
+   listed with ``xset q``::
+
+      mv 'SomeFont for Powerline.otf' ~/.local/share/fonts/
+
+#. Update font cache for the path the font was moved to (root privileges may be 
+   needed for updating font cache for some paths)::
+
+      fc-cache -vf ~/.local/share/fonts/
+
+After installing patched font terminal emulator, GVim or whatever application 
+powerline should work with must be configured to use the patched font. The 
+correct font usually ends with *for Powerline*.
+
+If custom symbols cannot be seen then try closing all instances of the terminal 
+emulator. X server may need to be restarted for the changes to take effect.
+
+If custom symbols *still* can’t be seen then double-check that the font have 
+been installed to a valid X font path.
diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst
new file mode 100644
index 0000000..1d6fafc
--- /dev/null
+++ b/docs/source/installation/osx.rst
@@ -0,0 +1,71 @@
+********************
+Installation on OS X
+********************
+
+Python package
+==============
+
+1. Install a proper Python version (see `issue #39 
+   <https://github.com/powerline/powerline/issues/39>`_ for a discussion 
+   regarding the required Python version on OS X)::
+
+       sudo port select python python27-apple
+
+   Homebrew may be used here::
+
+       brew install python
+
+   .. note::
+      There are three variants of the powerline client.  The fastest is
+      written in C and will be compiled if the compiler and libraries are
+      detected during installation.  The second fastest option is
+      :file:`powerline.sh` which requires ``socat`` and ``coreutils``.
+      ``coreutils`` may be installed using ``brew install 
+      coreutils``.  If neither of these are viable, then Powerline will
+      utilize a fallback client written in Python.
+
+2. Install Powerline using one of the following commands:
+
+   .. code-block:: sh
+
+       pip install --user powerline-status
+
+   will get current release version and
+
+   .. code-block:: sh
+
+       pip install --user git+https://github.com/powerline/powerline
+
+   will get latest development version.
+
+   .. warning::
+      When using ``brew install`` to install Python one must not supply
+      ``--user`` flag to ``pip``.
+
+   .. note::
+      Due to the naming conflict with an unrelated project powerline is named 
+      ``powerline-status`` in PyPI.
+
+   .. note::
+      Powerline developers should be aware that ``pip install --editable`` does 
+      not currently fully work. Installation performed this way are missing 
+      ``powerline`` executable that needs to be symlinked. It will be located in 
+      ``scripts/powerline``.
+
+Vim installation
+================
+
+Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, 
+but MacVim users need to install it using the following command::
+
+    brew install macvim --env-std --with-override-system-vim
+
+Fonts installation
+==================
+
+To install patched font double-click the font file in Finder, then click 
+:guilabel:`Install this font` in the preview window.
+
+After installing the patched font MacVim or terminal emulator (whatever 
+application powerline should work with) need to be configured to use the patched 
+font. The correct font usually ends with *for Powerline*.
diff --git a/docs/source/license-and-credits.rst b/docs/source/license-and-credits.rst
new file mode 100644
index 0000000..5226669
--- /dev/null
+++ b/docs/source/license-and-credits.rst
@@ -0,0 +1,31 @@
+*******************
+License and credits
+*******************
+
+Powerline is licensed under the `MIT license
+<https://raw.github.com/powerline/powerline/develop/LICENSE>`_.
+
+..
+    This document is parsed by powerline_automan.py module. Do not forget to 
+    check that file before altering this one. Specifically it expects 
+    ``Authors`` and ``Contributors`` sections underlined by ``---``, a list of 
+    authors in format ``* `{name} <`` in the “Authors” section and fonts 
+    contributor name in format ``The glyphs in the font patcher are created by 
+    {name},`` in the “Contributors” section.
+
+Authors
+-------
+
+* `Kim Silkebækken <https://github.com/Lokaltog>`_
+* `Nikolay Pavlov <https://github.com/ZyX-I>`_
+* `Kovid Goyal <https://github.com/kovidgoyal>`_
+
+Contributors
+------------
+
+* `List of contributors
+  <https://github.com/powerline/powerline/contributors>`_
+* The glyphs in the font patcher are created by Fabrizio Schiavi, creator of
+  the excellent coding font `Pragmata Pro`_.
+
+.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
new file mode 100644
index 0000000..13b6be3
--- /dev/null
+++ b/docs/source/overview.rst
@@ -0,0 +1,67 @@
+********
+Overview
+********
+
+**Powerline is a statusline plugin for vim, and provides statuslines and
+prompts for several other applications, including zsh, bash, tmux, IPython,
+Awesome, i3 and Qtile.**
+
+Features
+--------
+
+* **Extensible and feature rich, written in Python.** Powerline was
+  completely rewritten in Python to get rid of as much vimscript as
+  possible. This has allowed much better extensibility, leaner and better
+  config files, and a structured, object-oriented codebase with no mandatory
+  third-party dependencies other than a Python interpreter.
+* **Stable and testable code base.** Using Python has allowed unit testing
+  of all the project code. The code is tested to work in Python 2.6+ and
+  Python 3.
+* **Support for prompts and statuslines in many applications.** Originally
+  created exclusively for vim statuslines, the project has evolved to
+  provide statuslines in tmux and several WMs, and prompts for shells like
+  bash/zsh and other applications. It’s simple to write renderers for any
+  other applications that Powerline doesn’t yet support.
+* **Configuration and colorschemes written in JSON.** JSON is
+  a standardized, simple and easy to use file format that allows for easy
+  user configuration across all of Powerline’s supported applications.
+* **Fast and lightweight, with daemon support for even better performance.**
+  Although the code base spans a couple of thousand lines of code with no
+  goal of “less than X lines of code”, the main focus is on good performance
+  and as little code as possible while still providing a rich set of
+  features. The new daemon also ensures that only one Python instance is
+  launched for prompts and statuslines, which provides excellent
+  performance.
+
+*But I hate Python / I don’t need shell prompts / this is just too much
+hassle for me / what happened to the original vim-powerline project / …*
+
+You should check out some of the Powerline derivatives. The most lightweight
+and feature-rich alternative is currently the `vim-airline
+<https://github.com/vim-airline/vim-airline>`_ project.
+
+Screenshots
+-----------
+
+Vim statusline
+^^^^^^^^^^^^^^
+
+**Mode-dependent highlighting**
+
+* .. image:: _static/img/pl-mode-normal.png
+     :alt: Normal mode
+* .. image:: _static/img/pl-mode-insert.png
+     :alt: Insert mode
+* .. image:: _static/img/pl-mode-visual.png
+     :alt: Visual mode
+* .. image:: _static/img/pl-mode-replace.png
+     :alt: Replace mode
+
+**Automatic truncation of segments in small windows**
+
+* .. image:: _static/img/pl-truncate1.png
+     :alt: Truncation illustration
+* .. image:: _static/img/pl-truncate2.png
+     :alt: Truncation illustration
+* .. image:: _static/img/pl-truncate3.png
+     :alt: Truncation illustration
diff --git a/docs/source/powerline_autodoc.py b/docs/source/powerline_autodoc.py
new file mode 100644
index 0000000..eba42ed
--- /dev/null
+++ b/docs/source/powerline_autodoc.py
@@ -0,0 +1,64 @@
+# vim:fileencoding=utf-8:noet
+from __future__ import (unicode_literals, division, absolute_import, print_function)
+
+import os
+
+from inspect import formatargspec
+
+from sphinx.ext import autodoc
+
+from powerline.lint.inspect import getconfigargspec
+from powerline.segments import Segment
+from powerline.lib.unicode import unicode
+
+
+def formatvalue(val):
+	if type(val) is str:
+		return '="' + unicode(val, 'utf-8').replace('"', '\\"').replace('\\', '\\\\') + '"'
+	else:
+		return '=' + repr(val)
+
+
+class ThreadedDocumenter(autodoc.FunctionDocumenter):
+	'''Specialized documenter subclass for ThreadedSegment subclasses.'''
+	@classmethod
+	def can_document_member(cls, member, membername, isattr, parent):
+		return (isinstance(member, Segment) or
+			super(ThreadedDocumenter, cls).can_document_member(member, membername, isattr, parent))
+
+	def format_args(self):
+		argspec = getconfigargspec(self.object)
+		return formatargspec(*argspec, formatvalue=formatvalue).replace('\\', '\\\\')
+
+
+class Repr(object):
+	def __init__(self, repr_contents):
+		self.repr_contents = repr_contents
+
+	def __repr__(self):
+		return '<{0}>'.format(self.repr_contents)
+
+
+class EnvironDocumenter(autodoc.AttributeDocumenter):
+	@classmethod
+	def can_document_member(cls, member, membername, isattr, parent):
+		if type(member) is dict and member.get('environ') is os.environ:
+			return True
+		else:
+			return False
+
+	def import_object(self, *args, **kwargs):
+		ret = super(EnvironDocumenter, self).import_object(*args, **kwargs)
+		if not ret:
+			return ret
+		self.object = self.object.copy()
+		if 'home' in self.object:
+			self.object.update(home=Repr('home directory'))
+		self.object.update(environ=Repr('environ dictionary'))
+		return True
+
+
+def setup(app):
+	autodoc.setup(app)
+	app.add_autodocumenter(ThreadedDocumenter)
+	app.add_autodocumenter(EnvironDocumenter)
diff --git a/docs/source/powerline_automan.py b/docs/source/powerline_automan.py
new file mode 100644
index 0000000..85d241c
--- /dev/null
+++ b/docs/source/powerline_automan.py
@@ -0,0 +1,408 @@
+# vim:fileencoding=utf-8:noet
+from __future__ import (unicode_literals, division, absolute_import, print_function)
+
+import os
+import re
+import codecs
+
+from collections import namedtuple
+from argparse import REMAINDER
+
+from functools import reduce
+
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst.directives import unchanged_required
+from docutils import nodes
+
+from powerline.lib.unicode import u
+
+
+AUTHOR_LINE_START = '* `'
+GLYPHS_AUTHOR_LINE_START = '* The glyphs in the font patcher are created by '
+
+
+def get_authors():
+	credits_file = os.path.join(os.path.dirname(__file__), 'license-and-credits.rst')
+	authors = []
+	glyphs_author = None
+	with codecs.open(credits_file, encoding='utf-8') as CF:
+		section = None
+		prev_line = None
+		for line in CF:
+			line = line[:-1]
+			if line and not line.replace('-', ''):
+				section = prev_line
+			elif section == 'Authors':
+				if line.startswith(AUTHOR_LINE_START):
+					authors.append(line[len(AUTHOR_LINE_START):line.index('<')].strip())
+			elif section == 'Contributors':
+				if line.startswith(GLYPHS_AUTHOR_LINE_START):
+					assert(not glyphs_author)
+					glyphs_author = line[len(GLYPHS_AUTHOR_LINE_START):line.index(',')].strip()
+			prev_line = line
+	return {
+		'authors': ', '.join(authors),
+		'glyphs_author': glyphs_author,
+	}
+
+
+class AutoManSubparsers(object):
+	def __init__(self):
+		self.parsers = []
+
+	def add_parser(self, command, *args, **kwargs):
+		self.parsers.append((command, AutoManParser(*args, **kwargs)))
+		return self.parsers[-1][1]
+
+
+Argument = namedtuple('Argument', ('names', 'help', 'choices', 'metavar', 'required', 'nargs', 'is_option', 'is_long_option', 'is_short_option', 'multi', 'can_be_joined'))
+
+
+def parse_argument(*args, **kwargs):
+	is_option = args[0].startswith('-')
+	is_long_option = args[0].startswith('--')
+	is_short_option = is_option and not is_long_option
+	action = kwargs.get('action', 'store')
+	multi = kwargs.get('action') in ('append',) or kwargs.get('nargs') is REMAINDER
+	nargs = kwargs.get('nargs', (1 if action in ('append', 'store') else 0))
+	return Argument(
+		names=args,
+		help=u(kwargs.get('help', '')),
+		choices=[str(choice) for choice in kwargs.get('choices', [])],
+		metavar=kwargs.get('metavar') or args[-1].lstrip('-').replace('-', '_').upper(),
+		required=kwargs.get('required', False) if is_option else (
+			kwargs.get('nargs') not in ('?',)),
+		nargs=nargs,
+		multi=multi,
+		is_option=is_option,
+		is_long_option=is_long_option,
+		is_short_option=is_short_option,
+		can_be_joined=(is_short_option and not multi and not nargs)
+	)
+
+
+class AutoManGroup(object):
+	is_short_option = False
+	is_option = False
+	is_long_option = False
+	can_be_joined = False
+
+	def __init__(self):
+		self.arguments = []
+		self.required = False
+
+	def add_argument(self, *args, **kwargs):
+		self.arguments.append(parse_argument(*args, **kwargs))
+
+	def add_argument_group(self, *args, **kwargs):
+		self.arguments.append(AutoManGroup())
+		return self.arguments[-1]
+
+
+class SurroundWith():
+	def __init__(self, ret, condition, start='[', end=']'):
+		self.ret = ret
+		self.condition = condition
+		self.start = start
+		self.end = end
+
+	def __enter__(self, *args):
+		if self.condition:
+			self.ret.append(nodes.Text(self.start))
+
+	def __exit__(self, *args):
+		if self.condition:
+			self.ret.append(nodes.Text(self.end))
+
+
+def insert_separators(ret, sep):
+	for i in range(len(ret) - 1, 0, -1):
+		ret.insert(i, nodes.Text(sep))
+	return ret
+
+
+def format_usage_arguments(arguments, base_length=None):
+	line = []
+	prev_argument = None
+	arg_indexes = [0]
+	arguments = arguments[:]
+	while arguments:
+		argument = arguments.pop(0)
+		if isinstance(argument, nodes.Text):
+			line += [argument]
+			continue
+		can_join_arguments = (
+			argument.is_short_option
+			and prev_argument
+			and prev_argument.can_be_joined
+			and prev_argument.required == argument.required
+		)
+		if (
+			prev_argument
+			and not prev_argument.required
+			and prev_argument.can_be_joined
+			and not can_join_arguments
+		):
+			line.append(nodes.Text(']'))
+		arg_indexes.append(len(line))
+		if isinstance(argument, AutoManGroup):
+			arguments = (
+				[nodes.Text(' (')]
+				+ insert_separators(argument.arguments[:], nodes.Text(' |'))
+				+ [nodes.Text(' )')]
+				+ arguments
+			)
+		else:
+			if not can_join_arguments:
+				line.append(nodes.Text(' '))
+			with SurroundWith(line, not argument.required and not argument.can_be_joined):
+				if argument.can_be_joined and not can_join_arguments and not argument.required:
+					line.append(nodes.Text('['))
+				if argument.is_option:
+					line.append(nodes.strong())
+					name = argument.names[0]
+					if can_join_arguments:
+						name = name[1:]
+					# `--` is automatically transformed into &#8211; (EN DASH) 
+					# when parsing into HTML. We do not need this.
+					line[-1] += [nodes.Text(char) for char in name]
+				elif argument.nargs is REMAINDER:
+					line.append(nodes.Text('['))
+					line.append(nodes.strong())
+					line[-1] += [nodes.Text(char) for char in '--']
+					line.append(nodes.Text('] '))
+				if argument.nargs:
+					assert(argument.nargs in (1, '?', REMAINDER))
+					with SurroundWith(
+						line, (
+							True
+							if argument.nargs is REMAINDER
+							else (argument.nargs == '?' and argument.is_option)
+						)
+					):
+						if argument.is_long_option:
+							line.append(nodes.Text('='))
+						line.append(nodes.emphasis(text=argument.metavar))
+				elif not argument.is_option:
+					line.append(nodes.strong(text=argument.metavar))
+			if argument.multi:
+				line.append(nodes.Text('…'))
+		prev_argument = argument
+	if (
+		prev_argument
+		and prev_argument.can_be_joined
+		and not prev_argument.required
+	):
+		line.append(nodes.Text(']'))
+	arg_indexes.append(len(line))
+	ret = []
+	if base_length is None:
+		ret = line
+	else:
+		length = base_length
+		prev_arg_idx = arg_indexes.pop(0)
+		while arg_indexes:
+			next_arg_idx = arg_indexes.pop(0)
+			arg_length = sum((len(element.astext()) for element in line[prev_arg_idx:next_arg_idx]))
+			if length + arg_length > 68:
+				ret.append(nodes.Text('\n' + (' ' * base_length)))
+				length = base_length
+			ret += line[prev_arg_idx:next_arg_idx]
+			length += arg_length
+			prev_arg_idx = next_arg_idx
+	return ret
+
+
+LITERAL_RE = re.compile(r"`(.*?)'")
+
+
+def parse_argparse_text(text):
+	rst_text = LITERAL_RE.subn(r'``\1``', text)[0]
+	ret = []
+	for i, text in enumerate(rst_text.split('``')):
+		if i % 2 == 0:
+			ret.append(nodes.Text(text))
+		else:
+			ret.append(nodes.literal(text=text))
+	return ret
+
+
+def flatten_groups(arguments):
+	for argument in arguments:
+		if isinstance(argument, AutoManGroup):
+			for group_argument in flatten_groups(argument.arguments):
+				yield group_argument
+		else:
+			yield argument
+
+
+def format_arguments(arguments):
+	return [nodes.definition_list(
+		'', *[
+			nodes.definition_list_item(
+				'',
+				nodes.term(
+					# node.Text('') is required because otherwise for some 
+					# reason first name node is seen in HTML output as 
+					# `<strong>abc</strong>`.
+					'', *([nodes.Text('')] + (
+						insert_separators([
+							nodes.strong('', '', *[nodes.Text(ch) for ch in name])
+							for name in argument.names
+						], ', ')
+						if argument.is_option else
+						# Unless node.Text('') is here metavar is written in 
+						# bold in the man page.
+						[nodes.Text(''), nodes.emphasis(text=argument.metavar)]
+					) + (
+						[] if not argument.is_option or not argument.nargs else
+						[nodes.Text(' '), nodes.emphasis('', argument.metavar)]
+					))
+				),
+				nodes.definition('', nodes.paragraph('', *parse_argparse_text(argument.help or ''))),
+			)
+			for argument in flatten_groups(arguments)
+		] + [
+			nodes.definition_list_item(
+				'',
+				nodes.term(
+					'', nodes.Text(''),
+					nodes.strong(text='-h'),
+					nodes.Text(', '),
+					nodes.strong('', '', nodes.Text('-'), nodes.Text('-help')),
+				),
+				nodes.definition('', nodes.paragraph('', nodes.Text('Display help and exit.')))
+			)
+		]
+	)]
+
+
+def format_subcommand_usage(arguments, subcommands, progname, base_length):
+	return reduce((lambda a, b: a + reduce((lambda c, d: c + d), b, [])), [
+		[
+			[progname]
+			+ format_usage_arguments(arguments)
+			+ [nodes.Text(' '), nodes.strong(text=subcmd)]
+			+ format_usage_arguments(subparser.arguments)
+			+ [nodes.Text('\n')]
+			for subcmd, subparser in subparsers.parsers
+		]
+		for subparsers in subcommands
+	], [])
+
+
+def format_subcommands(subcommands):
+	return reduce((lambda a, b: a + reduce((lambda c, d: c + d), b, [])), [
+		[
+			[
+				nodes.section(
+					'',
+					nodes.title(text='Arguments specific to ' + subcmd + ' subcommand'),
+					*format_arguments(subparser.arguments),
+					ids=['subcmd-' + subcmd]
+				)
+			]
+			for subcmd, subparser in subparsers.parsers
+		]
+		for subparsers in subcommands
+	], [])
+
+
+class AutoManParser(object):
+	def __init__(self, description=None, help=None):
+		self.description = description
+		self.help = help
+		self.arguments = []
+		self.subcommands = []
+
+	def add_argument(self, *args, **kwargs):
+		self.arguments.append(parse_argument(*args, **kwargs))
+
+	def add_subparsers(self):
+		self.subcommands.append(AutoManSubparsers())
+		return self.subcommands[-1]
+
+	def add_mutually_exclusive_group(self):
+		self.arguments.append(AutoManGroup())
+		return self.arguments[-1]
+
+	def automan_usage(self, prog):
+		block = nodes.literal_block()
+		progname = nodes.strong()
+		progname += [nodes.Text(prog)]
+		base_length = len(prog)
+		if self.subcommands:
+			block += format_subcommand_usage(self.arguments, self.subcommands, progname, base_length)
+		else:
+			block += [progname]
+			block += format_usage_arguments(self.arguments, base_length)
+		return [block]
+
+	def automan_description(self):
+		ret = []
+		if self.help:
+			ret += parse_argparse_text(self.help)
+		ret += format_arguments(self.arguments) + format_subcommands(self.subcommands)
+		return ret
+
+
+class AutoMan(Directive):
+	required_arguments = 1
+	optional_arguments = 0
+	option_spec = dict(prog=unchanged_required, minimal=bool)
+	has_content = False
+
+	def run(self):
+		minimal = self.options.get('minimal')
+		module = self.arguments[0]
+		template_args = {}
+		template_args.update(get_authors())
+		get_argparser = __import__(str(module), fromlist=[str('get_argparser')]).get_argparser
+		parser = get_argparser(AutoManParser)
+		if minimal:
+			container = nodes.container()
+			container += parser.automan_usage(self.options['prog'])
+			container += parser.automan_description()
+			return [container]
+		synopsis_section = nodes.section(
+			'',
+			nodes.title(text='Synopsis'),
+			ids=['synopsis-section'],
+		)
+		synopsis_section += parser.automan_usage(self.options['prog'])
+		description_section = nodes.section(
+			'', nodes.title(text='Description'),
+			ids=['description-section'],
+		)
+		description_section += parser.automan_description()
+		author_section = nodes.section(
+			'', nodes.title(text='Author'),
+			nodes.paragraph(
+				'',
+				nodes.Text('Written by {authors} and contributors. The glyphs in the font patcher are created by {glyphs_author}.'.format(
+					**get_authors()
+				))
+			),
+			ids=['author-section']
+		)
+		issues_url = 'https://github.com/powerline/powerline/issues'
+		reporting_bugs_section = nodes.section(
+			'', nodes.title(text='Reporting bugs'),
+			nodes.paragraph(
+				'',
+				nodes.Text('Report {prog} bugs to '.format(
+					prog=self.options['prog'])),
+				nodes.reference(
+					issues_url, issues_url,
+					refuri=issues_url,
+					internal=False,
+				),
+				nodes.Text('.'),
+			),
+			ids=['reporting-bugs-section']
+		)
+		return [synopsis_section, description_section, author_section, reporting_bugs_section]
+
+
+def setup(app):
+	app.add_directive('automan', AutoMan)
diff --git a/docs/source/tips-and-tricks.rst b/docs/source/tips-and-tricks.rst
new file mode 100644
index 0000000..0af780e
--- /dev/null
+++ b/docs/source/tips-and-tricks.rst
@@ -0,0 +1,110 @@
+***************
+Tips and tricks
+***************
+
+Vim
+===
+
+Useful settings
+---------------
+
+You may find the following vim settings useful when using the Powerline
+statusline:
+
+.. code-block:: vim
+
+   set laststatus=2 " Always display the statusline in all windows
+   set showtabline=2 " Always display the tabline, even if there is only one tab
+   set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline)
+
+.. _tips-and-tricks-vscode:
+
+VS-Code
+=======
+
+Useful settings
+---------------
+
+To make powerline work in the internal terminal, add the following settings;
+where the shell command needs to be adjusted according to your preferred shell.
+
+.. code-block:: json
+
+   "terminal.integrated.shell.linux": "/bin/bash"
+   "terminal.integrated.inheritEnv": true
+
+.. _tips-and-tricks-urxvt:
+
+Rxvt-unicode
+============
+
+Terminus font and urxvt
+-----------------------
+
+The Terminus fonts does not have the powerline glyphs and unless someone submits 
+a patch to the font author, it is unlikely to happen.  However, Andre Klärner 
+came up with this work around: In your ``~/.Xdefault`` file add the following::
+
+  urxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12
+
+This will allow urxvt to fallback onto the Inconsolata fonts in case it does not 
+find the right glyphs within the terminus font.
+
+Source Code Pro font and urxvt
+------------------------------
+
+Much like the terminus font that was mentioned above, a similar fix can be 
+applied to the Source Code Pro fonts.
+
+In the ``~/.Xdefaults`` add the following::
+
+    URxvt*font: xft:Source\ Code\ Pro\ Medium:pixelsize=13:antialias=true:hinting=true,xft:Source\ Code\ Pro\ Medium:pixelsize=13:antialias=true:hinting=true
+
+I noticed that Source Code Pro has the glyphs there already, but the pixel size 
+of the fonts play a role in whether or not the > or the < separators showing up 
+or not. Using font size 12, glyphs on the right hand side of the powerline are 
+present, but the ones on the left don’t. Pixel size 14, brings the reverse 
+problem. Font size 13 seems to work just fine.
+
+Reloading powerline after update
+================================
+
+Once you have updated powerline you generally have the following options:
+
+#. Restart the application you are using it in. This is the safest one. Will not 
+   work if the application uses ``powerline-daemon``.
+#. For shell and tmux bindings (except for zsh with libzpython): do not do 
+   anything if you do not use ``powerline-daemon``, run ``powerline-daemon 
+   --replace`` if you do.
+#. Use powerline reloading feature.
+
+    .. warning::
+      This feature is an unsafe one. It is not guaranteed to work always, it may 
+      render your Python constantly error out in place of displaying powerline 
+      and sometimes may render your application useless, forcing you to 
+      restart.
+
+      *Do not report any bugs occurred when using this feature unless you know 
+      both what caused it and how this can be fixed.*
+
+   * When using zsh with libzpython use
+
+     .. code-block:: bash
+
+        powerline-reload
+
+     .. note:: This shell function is only defined when using libzpython.
+
+   * When using IPython use
+
+     ::
+
+        %powerline reload
+
+   * When using Vim use
+
+     .. code-block:: Vim
+
+        py powerline.reload()
+        " or (depending on Python version you are using)
+        py3 powerline.reload()
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
new file mode 100644
index 0000000..2b91747
--- /dev/null
+++ b/docs/source/troubleshooting.rst
@@ -0,0 +1,333 @@
+***************
+Troubleshooting
+***************
+
+System-specific issues
+======================
+
+.. toctree::
+
+   Linux <troubleshooting/linux>
+   OS X <troubleshooting/osx>
+
+Common issues
+=============
+
+After an update something stopped working
+-----------------------------------------
+
+Assuming powerline was working before update and stopped only after there are 
+two possible explanations:
+
+* You have more then one powerline installation (e.g. ``pip`` and ``Vundle`` 
+  installations) and you have updated only one.
+* Update brought some bug to powerline.
+
+In the second case you, of course, should report the bug to `powerline bug 
+tracker <https://github.com/powerline/powerline>`_.  In the first you should 
+make sure you either have only one powerline installation or you update all of 
+them simultaneously (beware that in the second case you are not supported). To 
+diagnose this problem you may do the following:
+
+#) If this problem is observed within the shell make sure that
+
+   .. code-block:: sh
+
+      python -c 'import powerline; print (powerline.__file__)'
+
+   which should report something like 
+   :file:`/usr/lib64/python2.7/site-packages/powerline/__init__.pyc` (if 
+   powerline is installed system-wide) or 
+   :file:`/home/USER/.../powerline/__init__.pyc` (if powerline was cloned 
+   somewhere, e.g. in :file:`/home/USER/.vim/bundle/powerline`) reports the same 
+   location you use to source in your shell configuration: in first case it 
+   should be some location in :file:`/usr` (e.g. 
+   :file:`/usr/share/zsh/site-contrib/powerline.zsh`), in the second it should 
+   be something like 
+   :file:`/home/USER/.../powerline/bindings/zsh/powerline.zsh`. If this is true 
+   it may be a powerline bug, but if locations do not match you should not 
+   report the bug until you observe it on configuration where locations do 
+   match.
+#) If this problem is observed specifically within bash make sure that you clean 
+   ``$POWERLINE_COMMAND`` and ``$PROMPT_COMMAND`` environment variables on 
+   startup or, at least, that it was cleaned after update. While different 
+   ``$POWERLINE_COMMAND`` variable should not cause any troubles most of time 
+   (and when it will cause troubles are rather trivial) spoiled 
+   ``$PROMPT_COMMAND`` may lead to strange error messages or absence of exit 
+   code reporting.
+
+   These are the sources which may keep outdated environment variables:
+
+   * Any command launched from any application inherits its environment unless 
+     callee explicitly requests to use specific environment. So if you did 
+     ``exec bash`` after update it is rather unlikely to fix the problem.
+   * More interesting: `tmux` is a client-server application, it keeps one 
+     server instance per one user. You probably already knew that, but there is 
+     an interesting consequence: once `tmux` server was started it inherits its 
+     environment from the callee and keeps it *forever* (i.e. until server is 
+     killed). This environment is then inherited by applications you start with 
+     ``tmux new-session``. Easiest solution is to kill tmux with ``tmux 
+     kill-server``, but you may also use ``tmux set-environment -u`` to unset 
+     offending variables.
+   * Also check `When using z powerline shows wrong number of jobs`_: though 
+     this problem should not be seen after update only, it contains another 
+     example of ``$PROMPT_COMMAND`` spoiling results.
+
+#) If this problem is observed within the vim instance you should check out the 
+   output of the following Ex mode commands
+
+   .. code-block:: vim
+
+      python import powerline as pl ; print (pl.__file__)
+      python3 import powerline as pl ; print (pl.__file__)
+
+   One (but not both) of them will most likely error out, this is OK. The same 
+   rules apply as in the 1), but in place of sourcing you should seek for the 
+   place where you modify `runtimepath` vim option. If you install powerline 
+   using `VAM <https://github.com/MarcWeber/vim-addon-manager>`_ then no 
+   explicit modifications of runtimpath were performed in your vimrc 
+   (runtimepath is modified by VAM in this case), but powerline will be placed 
+   in :file:`{plugin_root_dir}/powerline` where `{plugin_root_dir}` is stored in 
+   VAM settings dictionary: do `echo g:vim_addon_manager.plugin_root_dir`.
+
+There is a hint if you want to place powerline repository somewhere, but still 
+make powerline package importable anywhere: use
+
+  .. code-block:: sh
+
+     pip install --user --editable path/to/powerline
+
+Tmux/screen-related issues
+==========================
+
+I’m using tmux and Powerline looks like crap, what’s wrong?
+-----------------------------------------------------------
+
+* You need to tell tmux that it has 256-color capabilities. Add this to your 
+  :file:`.tmux.conf` to solve this issue::
+
+    set -g default-terminal "screen-256color"
+* If you’re using iTerm2, make sure that you have enabled the setting 
+  :guilabel:`Set locale variables automatically` in :menuselection:`Profiles --> 
+  Terminal --> Environment`.
+* Make sure tmux knows that terminal it is running in support 256 colors. You 
+  may tell it tmux by using ``-2`` option when launching it.
+
+I’m using tmux/screen and Powerline is colorless
+------------------------------------------------
+
+* If the above advices do not help, then you need to disable 
+  :ref:`term_truecolor <config-common-term_truecolor>`.
+* Alternative: set :ref:`additional_escapes <config-common-additional_escapes>` 
+  to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in 
+  screen, but in tmux it may produce ugly spaces.
+
+  .. warning::
+    Both tmux and screen are not resending sequences escaped in such a way. Thus 
+    even though additional escaping will work for the last shown prompt, 
+    highlighting will eventually go away when tmux or screen will redraw screen 
+    for some reason.
+
+    E.g. in screen it will go away when you used copy mode and prompt got out of 
+    screen and in tmux it will go away immediately after you press ``<Enter>``.
+
+In tmux there is a green bar in place of powerline
+--------------------------------------------------
+
+In order for tmux bindings to work ``powerline-config`` script is required to be 
+present in ``$PATH``. Alternatively one may define ``$POWERLINE_CONFIG_COMMAND`` 
+environment variable pointing to the location of the script. *This variable must 
+be defined prior to launching tmux server and in the environment where server is 
+started from.*
+
+Shell issues
+============
+
+Pipe status segment displays only last value in bash
+----------------------------------------------------
+
+Make sure that powerline command that sets prompt appears the very first in 
+``$PROMPT_COMMAND``. To do this ``powerline.sh`` needs to be sourced the very 
+last, after all other users of ``$PROMPT_COMMAND``.
+
+Bash prompt stopped updating
+----------------------------
+
+Make sure that powerline commands appear in ``$PROMPT_COMMAND``: some users of 
+``$PROMPT_COMMAND`` have a habit of overwriting the value instead of 
+prepending/appending to it. All powerline commands start with ``_powerline`` or 
+``powerline``, e.g. ``_powerline_set_prompt``.
+
+Bash prompt does not show last exit code
+----------------------------------------
+
+There are two possibilities here:
+
+* You are using ``default`` theme in place of ``default_leftonly``. Unlike 
+  ``default_leftonly`` ``default`` theme was designed for shells with right 
+  prompt support (e.g. zsh, tcsh, fish) and status in question is supposed to be 
+  shown on the right side which bash cannot display.
+
+* There is some other user of ``$PROMPT_COMMAND`` which prepended to this 
+  variable, but did not bother keeping the exit code. For the best experience 
+  powerline must appear first in ``$PROMPT_COMMAND`` which may be achieved by 
+  sourcing powerline bindings the last.
+
+  .. note::
+     Resourcing bash bindings will not resolve the problem unless you clear 
+     powerline commands from ``$PROMPT_COMMAND`` first.
+
+When sourcing shell bindings it complains about missing command or file
+-----------------------------------------------------------------------
+
+If you are using ``pip`` based installation do not forget to add pip-specific 
+executable path to ``$PATH`` environment variable. This path usually looks 
+something like ``$HOME/.local/bin`` (linux) or 
+``$HOME/Library/Python/{python_version}/bin`` (OS X). One may check out where 
+``powerline-config`` script was installed by using ``pip show -f 
+powerline-status | grep powerline-config`` (does not always work).
+
+I am suffering bad lags before displaying shell prompt
+------------------------------------------------------
+
+To get rid of these lags there currently are two options:
+
+* Run ``powerline-daemon``. Powerline does not automatically start it for you.
+  See installation instructions for more details.
+* Compile and install ``libzpython`` module that lives in 
+  https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.
+* If you are a python package manager, be sure to set ``POWERLINE_COMMAND``
+  to your Powerline command.  See installation instructions for details.
+  
+
+Prompt is spoiled after completing files in ksh
+-----------------------------------------------
+
+This is exactly why powerline has official mksh support, but not official ksh 
+support. If you know the solution feel free to share it in `powerline bug 
+tracker`_.
+
+When using z powerline shows wrong number of jobs
+-------------------------------------------------
+
+This happens because `z <https://github.com/rupa/z>`_ is launching some jobs in 
+the background from ``$POWERLINE_COMMAND`` and these jobs fail to finish before 
+powerline prompt is run.
+
+Solution to this problem is simple: be sure that :file:`z.sh` is sourced 
+strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background 
+jobs are spawned by `z <https://github.com/rupa/z>`_ after powerline has done 
+its job.
+
+When using shell I do not see powerline fancy characters
+--------------------------------------------------------
+
+If your locale encoding is not unicode (any encoding that starts with “utf” or 
+“ucs” will work, case is ignored) powerline falls back to ascii-only theme. You 
+should set up your system to use unicode locale or forget about powerline fancy 
+characters.
+
+Urxvt unicode3 and frills
+-------------------------
+
+Make sure that, whatever urxvt package you're installing, both the `unicode3`
+and `frills` features are enabled at compile time. Run
+``urxvt --help 2>&1 | grep options:`` to get a list of enabled options.
+This should contain at least `frills`, `unicode3` and optionally `iso14755`
+if you want to input Unicode characters as well.
+
+Compiler flags example:
+
+    --enable-frills \
+    --enable-unicode3
+
+As long as your terminal emulator is compiled without unicode rendering,
+no amount of configuration will make it display unicode characters.
+They're being considered 'unnecessary features', but they add negligible
+overhead to the size of the installed package (~100KB).
+
+Vim issues
+==========
+
+My vim statusline has strange characters like ``^B`` in it!
+-----------------------------------------------------------
+
+* Please add ``set encoding=utf-8`` to your :file:`vimrc`.
+
+My vim statusline has a lot of ``^`` or underline characters in it!
+-------------------------------------------------------------------
+
+* You need to configure the ``fillchars`` setting to disable statusline 
+  fillchars (see ``:h 'fillchars'`` for details). Add this to your :file:`vimrc` 
+  to solve this issue:
+
+   .. code-block:: vim
+
+      set fillchars+=stl:\ ,stlnc:\ 
+
+My vim statusline is hidden/only appears in split windows!
+----------------------------------------------------------
+
+* Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
+
+My vim statusline is not displayed completely and has too much spaces
+---------------------------------------------------------------------
+
+* Be sure you have ``ambiwidth`` option set to ``single``.
+* Alternative: set :ref:`ambiwidth <config-common-ambiwidth>` to 2, remove fancy 
+  dividers (they suck when ``ambiwidth`` is set to double).
+
+Powerline loses color after editing vimrc
+-----------------------------------------
+
+If your vimrc has something like
+
+.. code-block:: vim
+
+    autocmd! BufWritePost ~/.vimrc :source ~/.vimrc
+
+used to automatically source vimrc after saving it then you must add ``nested`` 
+after pattern (``vimrc`` in this case):
+
+.. code-block:: vim
+
+    autocmd! BufWritePost ~/.vimrc nested :source ~/.vimrc
+
+. Alternatively move ``:colorscheme`` command out of the vimrc to the file which 
+will not be automatically resourced.
+
+Observed problem is that when you use ``:colorscheme`` command existing 
+highlighting groups are usually cleared, including those defined by powerline. 
+To workaround this issue powerline hooks ``Colorscheme`` event, but when you 
+source vimrc with ``BufWritePost`` (or any other) event, but without ``nested`` 
+this event is not launched. See also `autocmd-nested 
+<http://vimcommunity.bitbucket.org/doc/autocmd.txt.html#autocmd-nested>`_ Vim 
+documentation.
+
+Powerline loses color after saving any file
+-------------------------------------------
+
+It may be one of the incarnations of the above issue: specifically minibufexpl 
+is known to trigger it. If you are using minibufexplorer you should set
+
+.. code-block:: vim
+
+    let g:miniBufExplForceSyntaxEnable = 1
+
+variable so that this issue is not triggered. Complete explanation:
+
+#. When MBE autocommand is executed it launches ``:syntax enable`` Vim command…
+#. … which makes Vim source :file:`syntax/syntax.vim` file …
+#. … which in turn sources :file:`syntax/synload.vim` …
+#. … which executes ``:colorscheme`` command. Normally this command triggers 
+   ``Colorscheme`` event, but in the first point minibufexplorer did set up 
+   autocommands that miss ``nested`` attribute meaning that no events will be 
+   triggered when processing MBE events.
+
+.. note::
+    This setting was introduced in version 6.3.1 of `minibufexpl 
+    <http://www.vim.org/scripts/script.php?script_id=159>`_ and removed in 
+    version 6.5.0 of its successor `minibufexplorer 
+    <http://www.vim.org/scripts/script.php?script_id=3239>`_. It is highly 
+    advised to use the latter because `minibufexpl`_ was last updated late in 
+    2004.
diff --git a/docs/source/troubleshooting/linux.rst b/docs/source/troubleshooting/linux.rst
new file mode 100644
index 0000000..e0493c6
--- /dev/null
+++ b/docs/source/troubleshooting/linux.rst
@@ -0,0 +1,78 @@
+************************
+Troubleshooting on Linux
+************************
+
+I can’t see any fancy symbols, what’s wrong?
+--------------------------------------------
+
+* Make sure that you’ve configured gvim or your terminal emulator to use 
+  a patched font.
+* You need to set your ``LANG`` and ``LC_*`` environment variables to 
+  a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro’s 
+  documentation for information about setting these variables correctly.
+* Make sure that vim is compiled with the ``--with-features=big`` flag.
+* If you’re using rxvt-unicode make sure that it’s compiled with the 
+  ``--enable-unicode3`` flag.
+* If you’re using xterm make sure you have told it to work with unicode. You may 
+  need ``-u8`` command-line argument, ``uxterm`` shell wrapper that is usually 
+  shipped with xterm for this or ``xterm*utf8`` property set to ``1`` or ``2`` 
+  in ``~/.Xresources`` (applied with ``xrdb``). Note that in case ``uxterm`` is 
+  used configuration is done via ``uxterm*…`` properties and not ``xterm*…``.
+
+  In any case the only absolute requirement is launching xterm with UTF-8 
+  locale.
+* If you are using bitmap font make sure that 
+  :file:`/etc/fonts/conf.d/70-no-bitmaps.conf` does not exist. If it does check 
+  out your distribution documentation to find a proper way to remove it (so that 
+  it won’t reappear after update). E.g. in Gentoo this is::
+
+      eselect fontconfig disable 70-no-bitmaps.conf
+
+  (currently this only removes the symlink from :file:`/etc/fonts/conf.d`). Also 
+  check out that no other fontconfig file does not have ``rejectfont`` tag that 
+  tells fontconfig to disable bitmap fonts (they are referenced as not 
+  scalable).
+
+The fancy symbols look a bit blurry or “off”!
+---------------------------------------------
+
+* Make sure that you have patched all variants of your font (i.e. both the 
+  regular and the bold font files).
+
+I am seeing strange blocks in place of playing/paused/stopped signs
+-------------------------------------------------------------------
+
+If you are using ``powerline_unicode7`` :ref:`top-level theme 
+<config-common-default_top_theme>` then symbols for player segments are taken 
+from U+23F4–U+23FA range which is missing from most fonts. You may fix the issue 
+by using `Symbola <http://users.teilar.gr/~g1951d/>`_ font (or any other font 
+which contains these glyphs).
+
+If your terminal emulator is using fontconfig library then you can create 
+a fontconfig configuration file with the following contents:
+
+.. code-block:: xml
+
+    <?xml version="1.0"?>
+    <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+
+    <fontconfig>
+    	<alias>
+    		<family>Terminus</family>
+    		<prefer><family>Symbola</family></prefer>
+    	</alias>
+    </fontconfig>
+
+(replace ``Terminus`` with the name of the font you are using). Exact sequence 
+of actions you need to perform is different across distributions, most likely it 
+will work if you put the above xml into 
+:file:`/etc/fonts/conf.d/99-prefer-symbola.conf`. On Gentoo you need to put it 
+into :file:`/etc/fonts/conf.d/99-prefer-symbola.conf` and run::
+
+    eselect fontconfig enable 99-prefer-symbola
+
+.
+
+.. warning::
+    This answer is only applicable if you use ``powerline_unicode7`` theme or if 
+    you configured powerline to use the same characters yourself.
diff --git a/docs/source/troubleshooting/osx.rst b/docs/source/troubleshooting/osx.rst
new file mode 100644
index 0000000..b61063e
--- /dev/null
+++ b/docs/source/troubleshooting/osx.rst
@@ -0,0 +1,71 @@
+***********************
+Troubleshooting on OS X
+***********************
+
+I can’t see any fancy symbols, what’s wrong?
+--------------------------------------------
+
+* If you’re using iTerm2, please update to `this revision 
+  <https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_ 
+  or newer. Also make sure that Preferences>Profiles>Text>Non-ASCII Font is the same as
+  your main Font.
+* You need to set your ``LANG`` and ``LC_*`` environment variables to 
+  a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro’s 
+  documentation for information about setting these variables correctly.
+
+The colors look weird in the default OS X Terminal app!
+-------------------------------------------------------
+
+* The arrows may have the wrong colors if you have changed the “minimum 
+  contrast” slider in the color tab of your OS X settings.
+* The default OS X Terminal app is known to have some issues with the 
+  Powerline colors. Please use another terminal emulator. iTerm2 should work 
+  fine.
+
+The colors look weird in iTerm2!
+--------------------------------
+
+* The arrows may have the wrong colors if you have changed the “minimum 
+  contrast” slider in the color tab of your OS X settings.
+* If you're using transparency, check “Keep background colors opaque”.
+
+Statusline is getting wrapped to the next line in iTerm2
+--------------------------------------------------------
+
+* Turn off “Treat ambigious-width characters as double width” in `Preferences 
+  --> Text`.
+* Alternative: remove fancy dividers (they suck in this case), set 
+  :ref:`ambiwidth <config-common-ambiwidth>` to 2.
+
+I receive a ``NameError`` when trying to use Powerline with MacVim!
+-------------------------------------------------------------------
+
+* Please install MacVim using this command::
+
+      brew install macvim --env-std --override-system-vim
+
+  Then install Powerline locally with ``pip install --user``, or by 
+  running these commands in the ``powerline`` directory::
+
+      ./setup.py build
+      ./setup.py install --user
+
+I receive an ``ImportError`` when trying to use Powerline on OS X!
+------------------------------------------------------------------
+
+* This is caused by an invalid ``sys.path`` when using system vim and system 
+  Python. Please try to select another Python distribution::
+
+      sudo port select python python27-apple
+
+* See `issue #39 <https://github.com/powerline/powerline/issues/39>`_ for 
+  a discussion and other possible solutions for this issue.
+
+I receive “FSEventStreamStart: register_with_server: ERROR” with status_colors
+------------------------------------------------------------------------------
+
+This is `a known <https://github.com/joyent/node/issues/5463>`_ libuv issue that 
+happens if one is trying to watch too many files. It should be fixed in 
+libuv-0.12. Until then it is suggested to either disable ``status_colors`` (from 
+:py:func:`powerline.segments.common.vcs.branch`) or choose stat-based watcher 
+(will have effectively the same effect as disabling ``status_colors``).
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
new file mode 100644
index 0000000..5bfd304
--- /dev/null
+++ b/docs/source/usage.rst
@@ -0,0 +1,88 @@
+*****
+Usage
+*****
+
+Application-specific requirements
+---------------------------------
+
+Vim plugin requirements
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The vim plugin requires a vim version with Python support compiled in. Presence 
+of Python support in Vim can be checked by running ``vim --version | grep 
++python``.
+
+If Python support is absent then Vim needs to be compiled with it. To do this 
+use ``--enable-pythoninterp`` :file:`./configure` flag (Python 3 uses 
+``--enable-python3interp`` flag instead). Note that this also requires the 
+related Python headers to be installed. Please consult distribution’s 
+documentation for details on how to compile and install packages.
+
+Vim version 7.4 or newer is recommended for performance reasons, but Powerline 
+supports Vim 7.0.112 and higher.
+
+Shell prompts requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Due to fish having incorrect code for prompt width calculations up to version 
+2.1 and no way to tell that certain sequence of characters has no width 
+(``%{…%}`` in zsh and ``\[…\]`` in bash prompts serve exactly this purpose) 
+users that have fish versions below 2.1 are not supported..
+
+
+WM widgets requirements
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Awesome is supported starting from version 3.5.1, inclusive. QTile is supported 
+from version 0.6, inclusive.
+
+.. _usage-terminal-emulators:
+
+Terminal emulator requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Powerline uses several special glyphs to get the arrow effect and some custom 
+symbols for developers. This requires either a symbol font or a patched font 
+installed. Used terminal emulator must also support either patched fonts or 
+fontconfig for Powerline to work properly.
+
+:ref:`24-bit color support <config-common-term_truecolor>` can also be enabled 
+if terminal emulator supports it.
+
+.. table:: Application/terminal emulator feature support matrix
+   :name: term-feature-support-matrix
+
+   ===================== ======= ===================== ===================== =====================
+   Name                  OS      Patched font support  Fontconfig support    24-bit color support 
+   ===================== ======= ===================== ===================== =====================
+   Gvim                  Linux   |i_yes|               |i_no|                |i_yes|
+   iTerm2                OS X    |i_yes|               |i_no|                |i_no|
+   Konsole               Linux   |i_yes|               |i_yes|               |i_yes|
+   lxterminal            Linux   |i_yes|               |i_yes|               |i_no|
+   MacVim                OS X    |i_yes|               |i_no|                |i_yes|
+   rxvt-unicode          Linux   |i_partial| [#]_      |i_no|                |i_no|
+   st                    Linux   |i_yes|               |i_yes|               |i_yes| [#]_
+   Terminal.app          OS X    |i_yes|               |i_no|                |i_no|
+   libvte-based [#]_     Linux   |i_yes|               |i_yes|               |i_yes| [#]_
+   xterm                 Linux   |i_yes|               |i_no|                |i_partial| [#]_
+   fbterm                Linux   |i_yes|               |i_yes|               |i_no|
+   ===================== ======= ===================== ===================== =====================
+
+.. |i_yes| image:: _static/img/icons/tick.png
+.. |i_no| image:: _static/img/icons/cross.png
+.. |i_partial| image:: _static/img/icons/error.png
+
+.. [#] Must be compiled with ``--enable-unicode3`` for the patched font to work.
+.. [#] Since version 0.5.
+.. [#] Including XFCE terminal and GNOME terminal.
+.. [#] Since version 0.36.
+.. [#] Uses nearest color from 8-bit palette.
+
+Plugins
+-------
+
+.. toctree::
+
+   usage/shell-prompts
+   usage/wm-widgets
+   usage/other
diff --git a/docs/source/usage/other.rst b/docs/source/usage/other.rst
new file mode 100644
index 0000000..ff0ccae
--- /dev/null
+++ b/docs/source/usage/other.rst
@@ -0,0 +1,224 @@
+*************
+Other plugins
+*************
+
+.. _vim-vimrc:
+
+Vim statusline
+==============
+
+If installed using pip just add
+
+.. code-block:: vim
+
+    python from powerline.vim import setup as powerline_setup
+    python powerline_setup()
+    python del powerline_setup
+
+(replace ``python`` with ``python3`` if appropriate) to the :file:`vimrc`.
+
+.. note::
+   Status line will not appear by default when there is only a single window
+   displayed. Run ``:h 'laststatus'`` in Vim for more information.
+
+If the repository was just cloned the following line needs to be added to the 
+:file:`vimrc`:
+
+.. code-block:: vim
+
+   set rtp+={repository_root}/powerline/bindings/vim
+
+where ``{repository_root}`` is the absolute path to the Powerline installation 
+directory (see :ref:`repository root <repository-root>`).
+
+If pathogen is used and Powerline functionality is not needed outside of Vim 
+then it is possible to simply add Powerline as a bundle and point the path above 
+to the Powerline bundle directory, e.g. 
+:file:`~/.vim/bundle/powerline/powerline/bindings/vim`.
+
+Vundle and NeoBundle users may instead use
+
+.. code-block:: vim
+
+    Bundle 'powerline/powerline', {'rtp': 'powerline/bindings/vim/'}
+
+(NeoBundle users need ``NeoBundle`` in place of ``Bundle``, otherwise setup is 
+the same).
+
+Vim-addon-manager setup is even easier because it is not needed to write this 
+big path or install anything by hand: ``powerline`` can be installed and 
+activated just like any other plugin using
+
+.. code-block:: vim
+
+    call vam#ActivateAddons(['powerline'])
+
+.. warning::
+    *Never* install powerline with pathogen/VAM/Vundle/NeoBundle *and* with pip. 
+    If powerline functionality is needed in applications other then Vim then 
+    system-wide installation (in case used OS distribution has powerline 
+    package), pip-only or ``pip install --editable`` kind of installation 
+    performed on the repository installed by Vim plugin manager should be used.
+
+    No issues are accepted in powerline issue tracker for double pip/non-pip 
+    installations, especially if these issues occur after update.
+
+.. note::
+    If supplied :file:`powerline.vim` file is used to load powerline there are 
+    additional configuration variables available: ``g:powerline_pycmd`` and 
+    ``g:powerline_pyeval``. First sets command used to load powerline: expected 
+    values are ``"py"`` and ``"py3"``. Second sets function used in statusline, 
+    expected values are ``"pyeval"`` and ``"py3eval"``.
+
+    If ``g:powerline_pycmd`` is set to the one of the expected values then 
+    ``g:powerline_pyeval`` will be set accordingly. If it is set to some other 
+    value then ``g:powerline_pyeval`` must also be set. Powerline will not check 
+    that Vim is compiled with Python support if ``g:powerline_pycmd`` is set to 
+    an unexpected value.
+
+    These values are to be used to specify the only Python that is to be loaded 
+    if both versions are present: Vim may disable loading one python version if 
+    other was already loaded. They should also be used if two python versions 
+    are able to load simultaneously, but powerline was installed only for 
+    python-3 version.
+
+Tmux statusline
+===============
+
+Add the following lines to :file:`.tmux.conf`, where ``{repository_root}`` is 
+the absolute path to the Powerline installation directory (see :ref:`repository 
+root <repository-root>`)::
+
+   source "{repository_root}/powerline/bindings/tmux/powerline.conf"
+
+.. note::
+    The availability of the ``powerline-config`` command is required for 
+    powerline support. The location of this script may be specified via 
+    the ``$POWERLINE_CONFIG_COMMAND`` environment variable.
+
+.. note::
+    It is advised to run ``powerline-daemon`` before adding the above line to 
+    tmux.conf. To do so add::
+
+        run-shell "powerline-daemon -q"
+
+    to :file:`.tmux.conf`.
+
+.. warning::
+    Segments which depend on current working directory (e.g. 
+    :py:func:`powerline.segments.common.vcs.branch`) require also setting up 
+    :ref:`shell bindings <usage-shell>`. It is not required to use powerline 
+    shell prompt, :ref:`components setting <config-ext-components>` allows to 
+    set up only powerline bindings for tmux without altering your prompt. 
+    Without setting up shell bindings powerline will use current working 
+    directory of *tmux server* which is probably not what you need.
+
+    Segments which depend on environment like 
+    :py:func:`powerline.segments.common.env.virtualenv` will not work at all 
+    (i.e. they will use environment of the tmux server), tracking environment 
+    changes is going to slow down shell a lot.
+
+    In any case it is suggested to avoid both kinds of segments in tmux 
+    :ref:`themes <config-themes>` because even support for tracking current 
+    directory is very limited:
+
+    #. It works only in shell. Should you e.g. run Vim and run ``:cd`` there you 
+       will get current working directory from shell.
+    #. It works only in local shell and requires configuring it.
+    #. Some shells are not supported at all.
+
+IPython prompt
+==============
+
+For IPython>=7.0, add the following line to
+:file:`~/.ipython/profile_default/ipython_config.py` file in the used profile:
+
+
+.. code-block:: Python
+
+    from powerline.bindings.ipython.since_7 import PowerlinePrompts
+    c.TerminalInteractiveShell.prompts_class = PowerlinePrompts
+
+.. note::
+    If certain graphical/colored elements are not showing, make sure `c.TerminalInteractiveShell.simple_prompt`
+    is set to `False` in your config. 
+    Setting ``simple_prompt`` to False after IPython-5.0 is required regardless 
+    of whether you use ``c.InteractiveShellApp.extensions`` setting or 
+    ``c.TerminalInteractiveShell.prompts_class``. But you probably already have 
+    this line because ``simple_prompt`` is set to ``False`` by default and IPython
+    is not very useful without it.
+
+For IPython>=5.0 and <7.0 it is suggested to use
+
+.. code-block:: Python
+
+    from powerline.bindings.ipython.since_5 import PowerlinePrompts
+    c = get_config()
+    c.TerminalInteractiveShell.simple_prompt = False
+    c.TerminalInteractiveShell.prompts_class = PowerlinePrompts
+    
+
+    
+For IPython>=5.0 and <7.0 you may use the below set up, but it is deprecated.    
+For IPython>=0.11 add the following line to
+:file:`~/.ipython/profile_default/ipython_config.py` file in the used profile:
+
+.. code-block:: Python
+
+    c = get_config()
+    c.InteractiveShellApp.extensions = [
+        'powerline.bindings.ipython.post_0_11'
+    ]
+
+For IPython<0.11 add the following lines to :file:`.ipython/ipy_user_conf.py`:
+
+.. code-block:: Python
+
+    # top
+    from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
+
+    # main() function (assuming ipython was launched without configuration to 
+    # create skeleton ipy_user_conf.py file):
+    powerline_setup()
+
+
+IPython=0.11* is not supported and does not work. IPython<0.10 was not 
+tested (not installable by pip).
+
+.. _pdb-prompt:
+
+PDB prompt
+==========
+
+To use Powerline with PDB prompt you need to use custom class. Inherit your 
+class from :py:class:`pdb.Pdb` and decorate it with 
+:py:func:`powerline.bindings.pdb.use_powerline_prompt`:
+
+.. code-block:: Python
+
+   import pdb
+
+   from powerline.bindings.pdb import use_powerline_prompt
+
+   @use_powerline_prompt
+   class MyPdb(pdb.Pdb):
+       pass
+
+   MyPdb.run('some.code.to.debug()')
+
+. Alternatively you may use
+
+.. code-block:: bash
+
+   python -mpowerline.bindings.pdb path/to/script.py
+
+just like you used ``python -m pdb``.
+
+.. note:
+   If you are using Python-2.6 you need to use ``python 
+   -mpowerline.bindings.pdb.__main__``, not what is shown above.
+
+.. warning:
+   Using PyPy (not PyPy3) forces ASCII-only prompts. In other cases unicode 
+   characters are allowed, even if you use `pdbpp 
+   <https://pypi.python.org/pypi/pdbpp>`_.
diff --git a/docs/source/usage/shell-prompts.rst b/docs/source/usage/shell-prompts.rst
new file mode 100644
index 0000000..17774da
--- /dev/null
+++ b/docs/source/usage/shell-prompts.rst
@@ -0,0 +1,161 @@
+.. _usage-shell:
+
+*************
+Shell prompts
+*************
+
+.. note::
+    Powerline can operate without a background daemon, but the shell performance
+    can be very slow.  The Powerline daemon improves this performance
+    significantly, but must be started separately. It is advised to add
+
+    .. code-block:: bash
+
+        powerline-daemon -q
+
+    before any other powerline-related code in the shell configuration file.
+
+Bash prompt
+===========
+
+Add the following line to the :file:`bashrc`, where ``{repository_root}`` is the 
+absolute path to the Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/bash/powerline.sh
+
+.. note::
+    Since without powerline daemon bash bindings are very slow PS2 
+    (continuation) and PS3 (select) prompts are not set up. Thus it is advised 
+    to use
+
+    .. code-block:: bash
+
+       powerline-daemon -q
+       POWERLINE_BASH_CONTINUATION=1
+       POWERLINE_BASH_SELECT=1
+       . {repository_root}/powerline/bindings/bash/powerline.sh
+
+    in the bash configuration file. Without ``POWERLINE_BASH_*`` variables PS2 
+    and PS3 prompts are computed exactly once at bash startup.
+
+.. warning::
+    At maximum bash continuation PS2 and select PS3 prompts are computed each 
+    time main PS1 prompt is computed. Thus putting e.g. current time into PS2 or 
+    PS3 prompt will not work as expected.
+
+    At minimum they are computed once on startup.
+
+Zsh prompt
+==========
+
+Add the following line to the :file:`zshrc`, where ``{repository_root}`` is the 
+absolute path to the Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/zsh/powerline.zsh
+
+Fish prompt
+===========
+
+Add the following line to :file:`config.fish`, where ``{repository_root}`` is 
+the absolute path to the Powerline installation directory (see :ref:`repository 
+root <repository-root>`):
+
+.. code-block:: bash
+
+   set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
+   powerline-setup
+
+.. warning:: Fish is supported only starting from version 2.1.
+
+Rcsh prompt
+===========
+
+Powerline supports Plan9 rc reimplementation *by Byron Rakitzis* packaged by 
+many \*nix distributions. To use it add
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/rc/powerline.rc
+
+(``{repository_root}`` is the absolute path to the Powerline installation 
+directory, see :ref:`repository root <repository-root>`) to :file:`rcrc` file 
+(usually :file:`~/.rcrc`) and make sure ``rc`` is started as a login shell (with 
+``-l`` argument): otherwise this configuration file is not read.
+
+.. warning::
+   Original Plan9 shell and its \*nix port are not supported because they are 
+   missing ``prompt`` special function (it is being called once before each 
+   non-continuation prompt). Since powerline could not support shell without 
+   this or equivalent feature some other not-so-critical features of that port 
+   were used.
+
+Busybox (ash), mksh and dash prompt
+=====================================
+
+After launching busybox run the following command:
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/shell/powerline.sh
+
+where ``{repository_root}`` is the absolute path to the Powerline installation 
+directory (see :ref:`repository root <repository-root>`).
+
+Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the 
+following in ``~/.profile``:
+
+.. code-block:: bash
+
+    if test "$0" != "${0#dash}" ; then
+        export ENV={repository_root}/powerline/bindings/shell/powerline.sh
+    fi
+
+.. note::
+    Dash users that already have ``$ENV`` defined should either put the ``. 
+    …/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which 
+    will source (using ``.`` command) both former ``$ENV`` file and 
+    :file:`powerline.sh` files and set ``$ENV`` to the path of this new file.
+
+.. warning::
+    Mksh users have to set ``$POWERLINE_SHELL_CONTINUATION`` and 
+    ``$POWERLINE_SHELL_SELECT`` to 1 to get PS2 and PS3 (continuation and 
+    select) prompts support respectively: as command substitution is not 
+    performed in these shells for these prompts they are updated once each time 
+    PS1 prompt is displayed which may be slow.
+
+    It is also known that while PS2 and PS3 update is triggered at PS1 update it 
+    is *actually performed* only *next* time PS1 is displayed which means that 
+    PS2 and PS3 prompts will be outdated and may be incorrect for this reason.
+
+    Without these variables PS2 and PS3 prompts will be set once at startup. 
+    This only touches mksh users: busybox and dash both have no such problem.
+
+.. warning::
+    Job count is using some weird hack that uses signals and temporary files for 
+    interprocess communication. It may be wrong sometimes. Not the case in mksh.
+
+.. warning::
+    Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in 
+    busybox 1.22.1 when using :file:`powerline.sh` script.
+    
+Python Virtual Environments (conda, pyenv)
+==========================================
+
+If your system uses virtual environments to manage different Python versions,
+such as pyenv or anaconda, these tools will add a performance delay to every
+shell prompt.  This delay can be bypassed by explicitly specifying your command
+path.
+
+    .. code-block:: bash
+
+        export POWERLINE_COMMAND={path_to_powerline}
+        
+where ``{path_to_powerline}`` is the full filepath for powerline.  If you
+installed Powerline within an environment, you can find this path for pyenv
+with ``pyenv which powerline`` or for conda with ``which powerline``.
diff --git a/docs/source/usage/wm-widgets.rst b/docs/source/usage/wm-widgets.rst
new file mode 100644
index 0000000..bc63da6
--- /dev/null
+++ b/docs/source/usage/wm-widgets.rst
@@ -0,0 +1,101 @@
+**********************
+Window manager widgets
+**********************
+
+Awesome widget
+==============
+
+.. note:: Powerline currently only supports awesome 3.5 and 4+.
+
+.. note:: The Powerline widget will spawn a shell script that runs in the 
+   background and updates the statusline with ``awesome-client``.
+
+Add the following to :file:`rc.lua`, where ``{repository_root}`` is the absolute 
+path to Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: lua
+
+   package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
+   require('powerline')
+
+Then add the ``powerline_widget`` to ``wibox``:
+
+.. code-block:: lua
+
+   -- awesome3.5
+   right_layout:add(powerline_widget)
+   
+   -- awesome4+
+   s.mywibox:setup {
+   ...
+     { -- Right widgets
+       ...
+       powerline_widget,
+     },
+   }
+
+Qtile widget
+============
+
+Add the following to :file:`~/.config/qtile/config.py`:
+
+.. code-block:: python
+
+   from libqtile.bar import Bar
+   from libqtile.config import Screen
+   from libqtile.widget import Spacer
+
+   from powerline.bindings.qtile.widget import PowerlineTextBox
+
+   screens = [
+       Screen(
+           top=Bar([
+                   PowerlineTextBox(update_interval=2, side='left'),
+                   Spacer(),
+                   PowerlineTextBox(update_interval=2, side='right'),
+               ],
+               35 # width
+           ),
+       ),
+   ]
+
+.. _lemonbar-usage:
+
+lemonbar (formerly bar-aint-recursive)
+======================================
+
+To run the bar simply start the binding script:
+
+    python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py
+
+You can specify options to be passed to ``lemonbar`` after ``--``, like so:
+
+    python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py --height 16 -- -f "Source Code Pro for Powerline-9"
+
+to run with i3, simply ``exec`` this in the i3 config file and set the ``--i3`` switch:
+
+    exec python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py --i3
+
+Running the binding in i3-mode will require `i3ipc <https://github.com/acrisci/i3ipc-python>`_.
+
+See the `lemonbar documentation <https://github.com/LemonBoy/bar>`_ for more 
+information and options.
+
+All ``powerline-lemonbar.py`` arguments:
+
+.. automan:: powerline.commands.lemonbar
+   :prog: powerline-lemonbar.py
+   :minimal: true
+
+I3 bar
+======
+
+Add the following to :file:`~/.config/i3/config`::
+
+    bar {
+        status_command python /path/to/powerline/bindings/i3/powerline-i3.py
+        font pango:PowerlineFont 12
+    }
+
+where ``PowerlineFont`` is any system font with powerline support.