Adding upstream version 2.8.3.upstream/2.8.3upstream

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

13 files changed, 1227 insertions, 0 deletions

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: