summaryrefslogtreecommitdiffstats
path: root/docs/source
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:40:16 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:40:16 +0000
commit3f25952c13d5847d510c0cae22a8ba876638d570 (patch)
tree02f505f016ed5a1029277dcae520d5e2a75906fb /docs/source
parentInitial commit. (diff)
downloadpowerline-3f25952c13d5847d510c0cae22a8ba876638d570.tar.xz
powerline-3f25952c13d5847d510c0cae22a8ba876638d570.zip
Adding upstream version 2.8.3.upstream/2.8.3upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--docs/source/_static/css/theme_overrides.css6
-rw-r--r--docs/source/_static/img/icons/cross.pngbin0 -> 473 bytes
-rw-r--r--docs/source/_static/img/icons/error.pngbin0 -> 543 bytes
-rw-r--r--docs/source/_static/img/icons/tick.pngbin0 -> 451 bytes
-rw-r--r--docs/source/_static/img/pl-mode-insert.pngbin0 -> 6894 bytes
-rw-r--r--docs/source/_static/img/pl-mode-normal.pngbin0 -> 6879 bytes
-rw-r--r--docs/source/_static/img/pl-mode-replace.pngbin0 -> 6949 bytes
-rw-r--r--docs/source/_static/img/pl-mode-visual.pngbin0 -> 6868 bytes
-rw-r--r--docs/source/_static/img/pl-truncate1.pngbin0 -> 6882 bytes
-rw-r--r--docs/source/_static/img/pl-truncate2.pngbin0 -> 5541 bytes
-rw-r--r--docs/source/_static/img/pl-truncate3.pngbin0 -> 3093 bytes
-rw-r--r--docs/source/commands.rst9
-rw-r--r--docs/source/commands/config.rst12
-rw-r--r--docs/source/commands/daemon.rst12
-rw-r--r--docs/source/commands/lint.rst14
-rw-r--r--docs/source/commands/main.rst12
-rw-r--r--docs/source/conf.py70
-rw-r--r--docs/source/configuration.rst151
-rw-r--r--docs/source/configuration/listers.rst35
-rw-r--r--docs/source/configuration/local.rst260
-rw-r--r--docs/source/configuration/reference.rst602
-rw-r--r--docs/source/configuration/segments.rst28
-rw-r--r--docs/source/configuration/segments/common.rst57
-rw-r--r--docs/source/configuration/segments/i3wm.rst6
-rw-r--r--docs/source/configuration/segments/pdb.rst7
-rw-r--r--docs/source/configuration/segments/shell.rst6
-rw-r--r--docs/source/configuration/segments/tmux.rst6
-rw-r--r--docs/source/configuration/segments/vim.rst46
-rw-r--r--docs/source/configuration/selectors.rst17
-rw-r--r--docs/source/configuration/selectors/vim.rst6
-rw-r--r--docs/source/develop.rst13
-rw-r--r--docs/source/develop/extensions.rst47
-rw-r--r--docs/source/develop/listers.rst49
-rw-r--r--docs/source/develop/local-themes.rst59
-rw-r--r--docs/source/develop/segments.rst547
-rw-r--r--docs/source/develop/tips-and-tricks.rst21
-rw-r--r--docs/source/index.rst28
-rw-r--r--docs/source/installation.rst131
-rw-r--r--docs/source/installation/linux.rst110
-rw-r--r--docs/source/installation/osx.rst71
-rw-r--r--docs/source/license-and-credits.rst31
-rw-r--r--docs/source/overview.rst67
-rw-r--r--docs/source/powerline_autodoc.py64
-rw-r--r--docs/source/powerline_automan.py408
-rw-r--r--docs/source/tips-and-tricks.rst110
-rw-r--r--docs/source/troubleshooting.rst333
-rw-r--r--docs/source/troubleshooting/linux.rst78
-rw-r--r--docs/source/troubleshooting/osx.rst71
-rw-r--r--docs/source/usage.rst88
-rw-r--r--docs/source/usage/other.rst224
-rw-r--r--docs/source/usage/shell-prompts.rst161
-rw-r--r--docs/source/usage/wm-widgets.rst101
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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.