Merge branch 'update-documentation' into develop

docs/source/configuration/listers.rst

@@ -29,7 +29,7 @@ Pdb listers
    :members:
 
 i3wm listers
-----------
+------------
 
 .. automodule:: powerline.listers.i3wm
    :members:

docs/source/configuration/reference.rst

@@ -191,6 +191,8 @@ Common configuration is a subdictionary that is a value of ``ext`` key in
     ``{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 

docs/source/usage/other.rst

@@ -100,6 +100,29 @@ root <repository-root>`)::
 
     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
 ==============
 
@@ -124,6 +147,22 @@ For IPython>=0.11 add the following line to
         'powerline.bindings.ipython.post_0_11'
     ]
 
+For IPython>=5.0 you may use the above set up, but it is deprecated. 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
+
+.. note::
+    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 IPython is not very useful without it.
+
 IPython=0.11* is not supported and does not work. IPython<0.10 was not 
 tested (not installable by pip).
 

docs/source/usage/shell-prompts.rst

@@ -1,3 +1,5 @@
+.. _usage-shell:
+
 *************
 Shell prompts
 *************