summaryrefslogtreecommitdiffstats
path: root/docs/source/configuration
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/configuration
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/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
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: