tyler.durden/powerline
1
0
Fork 0
mirror of https://github.com/powerline/powerline.git synced 2025-07-26 23:35:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

Copy documentation from old variant

Browse Source 
Note: fontpatcher documentation was removed.

Closes #632
Closes #769
This commit is contained in:
ZyX 2014-08-02 23:51:20 +04:00
parent c2379df50a
commit c043fa5e22
21 changed files with 1265 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/source/configuration-and-customization.rst
View File

@ -1,15 +0,0 @@
*******************************
Configuration and customization
*******************************
Quick setup guide
-----------------
References
----------
.. toctree::
:glob:
configuration-reference
segment-reference

3
docs/source/configuration-reference.rst
View File

@ -1,3 +0,0 @@
***********************
Configuration reference
***********************

112
docs/source/configuration.rst Normal file
View File

@ -0,0 +1,112 @@
*******************************
Configuration and customization
*******************************
.. note:: **You DO NOT have to fork the main GitHub repo to personalize your
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-colors>`
:file:`powerline/colorschemes/{name}.json`,
:file:`powerline/colorscheme/__main__.json`,
:file:`powerline/colorschemes/{extension}/{name}.json`
:ref:`Themes <config-themes>`
:file:`powerline/themes/{extension}/default.json`
The default configuration files are stored in the main package. User
configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for
Linux users, and in :file:`~/.config/powerline` for OS X users. This usually
corresponds to :file:`~/.config/powerline` on both platforms.
If you need per-instance configuration please refer to :ref:`Local configuration
overrides <local-configuration-overrides>`.
.. _quick-guide:
Quick setup guide
=================
This guide will help you with the initial configuration of Powerline.
Start by copying the entire set of default configuration files to the
corresponding path in your user config directory:
.. code-block:: sh
mkdir ~/.config/powerline
cp -R /path/to/powerline/config_files/* ~/.config/powerline
Each extension (vim, tmux, etc.) has its own theme, and they are located in
:file:`{config directory}/themes/{extension}/default.json`.
If you want to move, remove or customize any of the provided segments, 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.
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.
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
arguments:
.. code-block:: javascript
{
"name": "weather",
"priority": 50,
"args": {
"unit": "F",
"location_query": "oslo, norway"
}
},
References
==========
.. toctree::
:glob:
configuration/reference
configuration/segments
configuration/local

154
docs/source/configuration/local.rst Normal file
View File

@ -0,0 +1,154 @@
.. _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:
``g:powerline_config_overrides``
Dictionary, recursively merged with contents of
:file:`powerline/config.json`.
``g:powerline_theme_overrides__{theme_name}``
Dictionary, recursively merged with contents of
:file:`powerline/themes/vim/{theme_name}.json`. Note that this way you can’t
redefine some value (e.g. segment) in list, only the whole list itself: only
dictionaries are merged recursively.
``g:powerline_config_path``
Path (must be expanded, ``~`` shortcut is not supported). Points to the
directory 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.
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=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_option=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``.
Zsh/zpython overrides
=====================
Here overrides are controlled by similarly to the powerline script, but values
are taken from zsh variables.
``POWERLINE_CONFIG``
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_CONFIG``
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``,
but only subdictionaries for ``THEME_NAME`` key are merged with theme
configuration when theme with given name is requested.
``POWERLINE_CONFIG_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 zsh usually performs them on its
own if you set variable without quotes: ``POWERLINE_CONFIG_PATH=~/example``.
Expansion depends on zsh configuration.
Ipython overrides
=================
Ipython overrides depend on ipython version. Before ipython-0.11 you should pass
additional keyword arguments to setup() function. After ipython-0.11 you should
use ``c.Powerline.KEY``. 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.
``path``
Sets directory where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are
performed thus you cannot use paths starting with ``~/``.
Prompt command
==============
In addition to the above configuration options you can use
``$POWERLINE_COMMAND`` environment variable to tell shell or tmux to use
specific powerline implementation. This is mostly useful for putting powerline
into different directory or replacing ``powerline`` script with
``powerline-client`` for performance reasons.
.. note::
``$POWERLINE_COMMAND`` appears in shell scripts without quotes thus you can
specify additional parameters in bash. In zsh you will have to make
``$POWERLINE_COMMAND`` an array parameter to achieve the same result. In
tmux it is passed to ``eval`` and depends on the shell used.
POSIX-compatible shells, zsh, bash and fish will split this variable in this
case.
If you want to disable prompt in shell, but still have tmux support or if you
want to disable tmux support you can use variables
``$POWERLINE_NO_{SHELL}_PROMPT``/``$POWERLINE_NO_SHELL_PROMPT`` and
``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT``/``$POWERLINE_NO_SHELL_TMUX_SUPPORT``
(substitute ``{SHELL}`` with the name of the shell (all-caps) you want to
disable support for (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.
If you do not want to disable prompt in shell, but yet do not want to launch
python twice to get :ref:`above <config-themes-above>` lines you do not use in
tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or
``$POWERLINE_NO_SHELL_ABOVE`` variable.
If you do not want to see additional space which is added to the right prompt in
fish in order to support multiline prompt you should set
``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables.
.. note::
Most supported shells’ configuration scripts check for additional
configuration variables being empty. But tcsh configuration script checks
for variables being *defined*, not empty.

367
docs/source/configuration/reference.rst Normal file
View File

@ -0,0 +1,367 @@
***********************
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 your terminal emulator supports 24-bit colors.
.. _config-common-ambiwidth:
``ambiwidth``
Tells powerline what to do with characters with East Asian Width Class
Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek
letters, Cyrillic letters). Valid values: any positive integer; it is
suggested that you only set it to 1 (default) or 2.
``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.
======= ===================================
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
(unless you are sure you always need it). 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).
``dividers``
Defines the dividers used in all Powerline extensions. This option
should usually only be changed if you don't have a patched font, or if
you use a font patched with the legacy font patcher.
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-common-paths:
``paths``
Defines additional paths which will be searched for modules when using
:ref:`module segment option <config-themes-seg-module>`. Paths defined here
have priority when searching for modules.
``log_file``
Defines path which will hold powerline logs. If not present, logging will be
done to stderr.
``log_level``
String, determines logging level. Defaults to ``WARNING``.
``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 seprate 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``.
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.
``theme``
.. _config-ext-theme:
Defines the theme used for this extension.
``local_themes``
.. _config-ext-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.
.. _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 indicies.
* A list of hex color strings.
It is expected that you define gradients from least alert color to most
alert or use non-alert colors.
.. _config-colorschemes:
Colorschemes
============
:Location: :file:`powerline/colorschemes/{name}.json`,
:file:`powerline/colorscheme/__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>`.
``attr``
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 you do not
need any attributes leave this 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/{extension}/{name}.json`
``name``
Name of the theme.
.. _config-themes-default_module:
``default_module``
Python module where segments will be looked by default.
.. _config-themes-segment_data:
``segment_data``
A dict where keys are segment names or strings ``{module}.{name}``. Used to
specify default values for various keys:
:ref:`after <config-theme-seg-after>`,
:ref:`args <config-themes-seg-args>` (only for function segments),
:ref:`before <config-theme-seg-before>`,
:ref:`contents <config-theme-seg-contents>` (only for string segments
if :ref:`name <config-themes-seg-name>` is defined),
:ref:`display <config-theme-seg-display`.
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.
``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:
``type``
The segment type. Can be one of ``function`` (default), ``string``
or ``filler``:
``function``
The segment contents is the return value of the function defined
in the :ref:`name option <config-themes-seg-name>`.
``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_group
option <config-themes-seg-highlight_group>`.
``module``
.. _config-themes-seg-module:
Function module, only required for function segments. Defaults to
``powerline.segments.{extension}``. Default is overriden by
:ref:`default_module theme option <config-themes-default_module>`.
``name``
.. _config-themes-seg-name:
Function name, only required for function segments.
``highlight_group``
.. _config-themes-seg-highlight_group:
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.
``before``
.. _config-themes-seg-before:
A string which will be prepended to the segment contents.
``after``
.. _config-themes-seg-after:
A string which will be appended to the segment contents.
``contents``
.. _config-themes-seg-contents:
Segment contents, only required for ``string`` segments.
``args``
.. _config-themes-seg-args:
A dict of arguments to be passed to a ``function`` segment.
``align``
Aligns the segments contents to the left (``l``), center (``c``) or
right (``r``).
``width``
.. _config-themes-seg-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.
``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 being removed first.
``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``.
``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``.
``exclude_modes``
A list of modes where this segment will be excluded: The segment is
included in all modes, *except* for the modes in this list.
``include_modes``
A list of modes where this segment will be included: The segment is
*not* included in any modes, *except* for the modes in this list.
``display``
.. _config-themes-seg-display:
Boolean. If false disables displaying of the segment.
Defaults to ``True``.

32
docs/source/configuration/segments.rst Normal file
View File

@ -0,0 +1,32 @@
*****************
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.
A segment function must return one of the following values:
* ``None``, which will remove the segment from the prompt/statusline.
* A string, which will be the segment contents.
* A list of dicts consisting of a ``contents`` string, and
a ``highlight_group`` list. This is useful for providing a particular
highlighting group depending on the segment contents.
Available segments
==================
.. toctree::
:glob:
segments/*

0
docs/source/segment-reference/common.rst → docs/source/configuration/segments/common.rst
View File

0
docs/source/segment-reference/shell.rst → docs/source/configuration/segments/shell.rst
View File

0
docs/source/segment-reference/vim.rst → docs/source/configuration/segments/vim.rst
View File

2
docs/source/index.rst
View File

@ -9,7 +9,7 @@ Powerline
overview overview
installation installation
usage usage
configuration-and-customization configuration
troubleshooting troubleshooting
tips-and-tricks tips-and-tricks
license-and-credits license-and-credits

47
docs/source/installation.rst
View File

@ -2,6 +2,53 @@
Installation Installation
************ ************
Generic requirements
====================
* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later. It is the only
non-optional requirement.
* C compiler. Required to build powerline client on linux. If it is not present
then powerline will fall back to shell script or python client.
* ``socat`` program. Required for shell variant of client which runs a bit
faster than python version of the client, but still slower than C version.
* ``psutil`` python package. Required for some segments like cpu_percent. Some
segments have linux-only fallbacks for ``psutil`` functionality.
* ``mercurial`` python package (note: *not* standalone executable). Required to
work with mercurial repositories.
* ``pygit2`` python package or ``git`` executable. Required to work with ``git``
repositories.
* ``bzr`` python package (note: *not* standalone executable). Required to work
with bazaar repositories.
* ``i3-py``, `available on github <https://github.com/ziberna/i3-py>`_. Required
for i3wm bindings and segments.
.. note::
Until mercurial and bazaar support Python-3 or PyPy powerline will not
support repository information when running in these interpreters.
Pip installation
================
This project is currently unavailable from PyPI due to a naming conflict with an
unrelated project, thus you will have to use the following command to install
powerline with ``pip``::
pip install --user git+git://github.com/Lokaltog/powerline
. You may also choose to clone powerline repository somewhere and use::
pip install -e --user {path_to_powerline}
, but note that in this case ``pip`` will not install ``powerline`` executable
and you will have to do something like::
ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
(:file:`~/.local/bin` should be replaced with some path present in ``$PATH``).
Installation on various platforms
=================================
.. toctree:: .. toctree::
Linux <installation/linux> Linux <installation/linux>

28
docs/source/installation/linux.rst
View File

@ -2,8 +2,28 @@
Installation on Linux Installation on Linux
********************* *********************
Requirements The following distribution-specific packages are officially supported, and they
------------ provide an easy way of installing and upgrading Powerline. The packages will
automatically do most of the configuration for you.
Installation * `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_
------------ * `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
* Gentoo Live ebuild in `raiagent <https://github.com/leycec/raiagent>`_ overlay
If you're running a distribution without an official package you'll have to
follow the installation guide below:
1. Install Python 3.2+ or Python 2.6+ with ``pip``. This step is
distribution-specific, so no commands provided.
2. Install Powerline using the following command::
pip install --user git+git://github.com/Lokaltog/powerline
.. note:: You need to use the GitHub URI when installing Powerline! This
project is currently unavailable on the PyPI due to a naming conflict
with an unrelated project.
.. note:: If you are powerline developer you should be aware that ``pip install
--editable`` does not currently fully work. If you
install powerline this way you will be missing ``powerline`` executable and
need to symlink it. It will be located in ``scripts/powerline``.

41
docs/source/installation/osx.rst
View File

@ -2,8 +2,41 @@
Installation on OS X Installation on OS X
******************** ********************
Requirements Python package
------------ ==============
Installation 1. Install a proper Python version (see `issue #39
------------ <https://github.com/Lokaltog/powerline/issues/39>`_ for a discussion
regarding the required Python version on OS X)::
sudo port select python python27-apple
. You may use homebrew for this::
brew install python
.
2. Install Powerline using the following command::
pip install --user git+git://github.com/Lokaltog/powerline
.. warning:: When using ``brew install`` to install Python one must not supply
``--user`` flag to ``pip``.
.. note:: You need to use the GitHub URI when installing Powerline! This
project is currently unavailable on the PyPI due to a naming conflict
with an unrelated project.
.. note:: If you are powerline developer you should be aware that ``pip install
--editable`` does not currently fully work. If you install powerline this way
you will be missing ``powerline`` executable and need to symlink it. It will
be located in ``scripts/powerline``.
Vim installation
================
Any terminal vim version with Python 3.2+ or Python 2.6+ support should work,
but if you're using MacVim you need to install it using the following command::
brew install macvim --env-std --override-system-vim

8
docs/source/segment-reference.rst
View File

@ -1,8 +0,0 @@
*****************
Segment reference
*****************
.. toctree::
:glob:
segment-reference/*

143
docs/source/troubleshooting.rst
View File

@ -2,7 +2,150 @@
Troubleshooting Troubleshooting
*************** ***************
System-specific issues
======================
.. toctree:: .. toctree::
Linux <troubleshooting/linux> Linux <troubleshooting/linux>
OS X <troubleshooting/osx> OS X <troubleshooting/osx>
Common issues
=============
I'm using tmux and Powerline looks like crap, what's wrong?
-----------------------------------------------------------
* You need to tell tmux that it has 256-color capabilities. Add this to your
:file:`.tmux.conf` to solve this issue::
set -g default-terminal "screen-256color"
* If you're using iTerm2, make sure that you have enabled the setting
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles
--> Terminal --> Environment`.
I’m using tmux/screen and Powerline is colorless
------------------------------------------------
* If the above advices do not help, then you need to disable
:ref:`term_truecolor <config-common-term_truecolor>`.
* Alternative: set :ref:`additional_escapes <config-common-additional_escapes>`
to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in
screen, but in tmux it may produce ugly spaces.
After an update something stopped working
-----------------------------------------
Assuming powerline was working before update and stopped only after there are
two possible explanations:
* You have more then one powerline installation (e.g. ``pip`` and ``Vundle``
installations) and you have updated only one.
* Update brought some bug to powerline.
In the second case you, of course, should report the bug to `powerline bug
tracker <https://github.com/Lokaltog/powerline>`_. In the first you should make
sure you either have only one powerline installation or you update all of them
simultaneously (beware that in the second case you are not supported). To
diagnose this problem you may do the following:
#) If this problem is observed within the shell make sure that
.. code-block:: sh
python -c 'import powerline; print (powerline.__file__)'
which should report something like
:file:`/usr/lib64/python2.7/site-packages/powerline/__init__.pyc` (if
powerline is installed system-wide) or
:file:`/home/USER/.../powerline/__init__.pyc` (if powerline was cloned
somewhere, e.g. in :file:`/home/USER/.vim/bundle/powerline`) reports the same
location you use to source in your shell configuration: in first case it
should be some location in :file:`/usr` (e.g.
:file:`/usr/share/zsh/site-contrib/powerline.zsh`), in the second it should
be something like
:file:`/home/USER/.../powerline/bindings/zsh/powerline.zsh`. If this is true
it may be a powerline bug, but if locations do not match you should not
report the bug until you observe it on configuration where locations do
match.
#) If this problem is observed within the vim instance you should check out the
output of the following Ex mode commands
.. code-block:: vim
python import powerline as pl ; print (pl.__file__)
python3 import powerline as pl ; print (pl.__file__)
One (but not both) of them will most likely error out, this is OK. The same
rules apply as in the 1), but in place of sourcing you should seek for the
place where you modify `runtimepath` vim option. If you install powerline
using `VAM <https://github.com/MarcWeber/vim-addon-manager>`_ then no
explicit modifications of runtimpath were performed in your vimrc
(runtimepath is modified by VAM in this case), but powerline will be placed
in :file:`{plugin_root_dir}/powerline` where `{plugin_root_dir}` is stored in
VAM settings dictionary: do `echo g:vim_addon_manager.plugin_root_dir`.
There is a hint if you want to place powerline repository somewhere, but still
make powerline package importable anywhere: use
.. code-block:: sh
pip install --user --editable path/to/powerline
My vim statusline has strange characters like ``^B`` in it!
-----------------------------------------------------------
* Please add ``set encoding=utf-8`` to your :file:`vimrc`.
My vim statusline has a lot of ``^`` or underline characters in it!
-------------------------------------------------------------------
* You need to configure the ``fillchars`` setting to disable statusline
fillchars (see ``:h fillchars`` for details). Add this to your
:file:`vimrc` to solve this issue:
.. code-block:: vim
set fillchars+=stl:\ ,stlnc:\
My vim statusline is hidden/only appears in split windows!
----------------------------------------------------------
* Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
My vim statusline is not displayed completely and has too much spaces
---------------------------------------------------------------------
* Be sure you have ``ambiwidth`` option set to ``single``.
* Alternative: set :ref:`ambiwidth <config-common-ambiwidth>` to 2, remove fancy
dividers (they suck when ``ambiwidth`` is set to double).
When using z powerline shows wrong number of jobs
-------------------------------------------------
This happens because `z <https://github.com/rupa/z>`_ is launching some jobs in
the background from ``$POWERLINE_COMMAND`` and these jobs fail to finish before
powerline prompt is run.
Solution to this problem is simple: be sure that :file:`z.sh` is sourced
strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background
jobs are spawned by `z <https://github.com/rupa/z>`_ after powerline has done
its job.
I am suffering bad lags before displaying shell prompt
------------------------------------------------------
To get rid of these lags there currently are two options:
* Run ``powerline-daemon``. Powerline does not automatically start it for you.
* Compile and install ``libzpython`` module that lives in
https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.
Prompt is spoiled after completing files in ksh
-----------------------------------------------
This is exactly why powerline has official mksh support, but not official ksh
support. If you know the solution feel free to share it in `powerline bug
tracker`_.

18
docs/source/troubleshooting/linux.rst
View File

@ -1,3 +1,21 @@
************************ ************************
Troubleshooting on Linux Troubleshooting on Linux
************************ ************************
I can't see any fancy symbols, what's wrong?
--------------------------------------------
* Make sure that you've configured gvim or your terminal emulator to use
a patched font.
* You need to set your ``LANG`` and ``LC_*`` environment variables to
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
documentation for information about setting these variables correctly.
* Make sure that vim is compiled with the ``--with-features=big`` flag.
* If you're using rxvt-unicode, make sure that it's compiled with the
``--enable-unicode3`` flag.
The fancy symbols look a bit blurry or "off"!
---------------------------------------------
* Make sure that you have patched all variants of your font (i.e. both the
regular and the bold font files).

58
docs/source/troubleshooting/osx.rst
View File

@ -1,3 +1,61 @@
*********************** ***********************
Troubleshooting on OS X Troubleshooting on OS X
*********************** ***********************
I can't see any fancy symbols, what's wrong?
--------------------------------------------
* If you're using iTerm2, please update to `this revision
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
or newer.
* You need to set your ``LANG`` and ``LC_*`` environment variables to
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
documentation for information about setting these variables correctly.
The colors look weird in the default OS X Terminal app!
-------------------------------------------------------
* The arrows may have the wrong colors if you have changed the "minimum
contrast" slider in the color tab of your OS X settings.
* The default OS X Terminal app is known to have some issues with the
Powerline colors. Please use another terminal emulator. iTerm2 should work
fine.
The colors look weird in iTerm2!
--------------------------------
* The arrows may have the wrong colors if you have changed the "minimum
contrast" slider in the color tab of your OS X settings.
* Please disable background transparency to resolve this issue.
Statusline is getting wrapped to the next line in iTerm2
--------------------------------------------------------
* Turn off “Treat ambigious-width characters as double width” in `Preferences
--> Text`.
* Alternative: remove fancy dividers (they suck in this case), set
:ref:`ambiwidth <config-common-ambiwidth>` to 2.
I receive a ``NameError`` when trying to use Powerline with MacVim!
-------------------------------------------------------------------
* Please install MacVim using this command::
brew install macvim --env-std --override-system-vim
Then install Powerline locally with ``pip install --user``, or by
running these commands in the ``powerline`` directory::
./setup.py build
./setup.py install --user
I receive an ``ImportError`` when trying to use Powerline on OS X!
------------------------------------------------------------------
* This is caused by an invalid ``sys.path`` when using system vim and system
Python. Please try to select another Python distribution::
sudo port select python python27-apple
* See `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ for
a discussion and other possible solutions for this issue.

58
docs/source/usage.rst
View File

@ -2,8 +2,62 @@
Usage Usage
***** *****
Application support matrix Application-specific requirements
-------------------------- ---------------------------------
Vim plugin requirements
^^^^^^^^^^^^^^^^^^^^^^^
The vim plugin requires a vim version with Python support compiled in. You
can check if your vim supports Python by running ``vim --version | grep
+python``.
If your vim version doesn't have support for Python, you'll have to compile
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if
you want Python 3 support instead). Note that this also requires the related
Python headers to be installed on your system. Please consult your
distribution's documentation for details on how to compile and install
packages.
Vim version 7.3.661 or newer is recommended for performance reasons.
Terminal emulator requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Powerline uses several special glyphs to get the arrow effect and some
custom symbols for developers. This requires that you either have a symbol
font or a patched font on your system. Your terminal emulator must also
support either patched fonts or fontconfig for Powerline to work properly.
You can also enable :ref:`24-bit color support <config-common-term_truecolor>`
if your terminal emulator supports it.
.. table:: Application/terminal emulator feature support matrix
:name: term-feature-support-matrix
===================== ======= ===================== ===================== =====================
Name OS Patched font support Fontconfig support 24-bit color support
===================== ======= ===================== ===================== =====================
Gnome Terminal Linux |i_yes| |i_yes| |i_no|
Gvim Linux |i_yes| |i_no| |i_yes|
iTerm2 OS X |i_yes| |i_no| |i_no|
Konsole Linux |i_yes| |i_yes| |i_yes|
lxterminal Linux |i_yes| |i_yes| |i_no|
MacVim OS X |i_yes| |i_no| |i_yes|
rxvt-unicode Linux |i_partial| [#]_ |i_no| |i_no|
st Linux |i_yes| |i_yes| |i_no|
Terminal.app OS X |i_yes| |i_no| |i_no|
Xfce Terminal Linux |i_yes| |i_yes| |i_no|
xterm Linux |i_yes| |i_no| |i_partial| [#]_
===================== ======= ===================== ===================== =====================
.. |i_yes| image:: _static/img/icons/tick.png
.. |i_no| image:: _static/img/icons/cross.png
.. |i_partial| image:: _static/img/icons/error.png
.. [#] Must be compiled with ``--enable-unicode3`` for the
patched font to work.
.. [#] Uses nearest color from 8-bit palette.
Plugins Plugins
------- -------

98
docs/source/usage/other.rst
View File

@ -2,5 +2,99 @@
Other plugins Other plugins
************* *************
tmux statusline .. _vim-vimrc:
---------------
Vim statusline
==============
If installed using pip just add
.. code-block:: vim
python from powerline.vim import setup as powerline_setup
python powerline_setup()
python del powerline_setup
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`.
If you just cloned the repository add the following line to your :file:`vimrc`,
where ``{repository_root}`` is the absolute path to your Powerline installation
directory:
.. code-block:: vim
set rtp+={repository_root}/powerline/bindings/vim
If you're using Vundle or Pathogen and don't want Powerline functionality in
any other applications, simply add Powerline as a bundle and point the path
above to the Powerline bundle directory, e.g.
``~/.vim/bundle/powerline/powerline/bindings/vim``. For vim-addon-manager it is
even easier since you don’t need to write this big path or install anything by
hand: ``powerline`` is installed and run just like any other plugin using
.. code-block:: vim
call vam#ActivateAddons(['powerline'])
.. note::
If you use supplied :file:`powerline.vim` file to load powerline there are
additional configuration variables available: ``g:powerline_pycmd`` and
``g:powerline_pyeval``. First sets command used to load powerline: expected
values are ``"py"`` and ``"py3"``. Second sets function used in statusline,
expected values are ``"pyeval"`` and ``"py3eval"``.
If ``g:powerline_pycmd`` is set to the one of the expected values then
``g:powerline_pyeval`` will be set accordingly. If it is set to some other
value then you must also set ``g:powerline_pyeval``. Powerline will not
check that Vim is compiled with Python support if you set
``g:powerline_pycmd`` to an unexpected value.
These values are to be used to specify the only Python that is to be loaded
if you have both versions: Vim may disable loading one python version if
other was already loaded. They should also be used if you have two python
versions able to load simultaneously, but with powerline installed only for
python-3 version.
Tmux statusline
===============
Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}``
is the absolute path to your Powerline installation directory::
source "{repository_root}/powerline/bindings/tmux/powerline.conf"
.. note::
The availability of the ``powerline-config`` command is required for
powerline support. You may specify location of this script via
``$POWERLINE_CONFIG_COMMAND`` environment variable.
.. note::
It is advised that you run ``powerline-daemon`` before adding the above line
to tmux.conf. To do so add::
run-shell "powerline-daemon -q"
to :file:`.tmux.conf`.
IPython prompt
==============
For IPython<0.11 add the following lines to your
:file:`.ipython/ipy_user_conf.py`::
# top
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
# main() function (assuming you launched ipython without configuration to
# create skeleton ipy_user_conf.py file):
powerline_setup()
For IPython>=0.11 add the following line to your :file:`ipython_config.py`
file in the profile you are using::
c.InteractiveShellApp.extensions = [
'powerline.bindings.ipython.post_0_11'
]
IPython=0.11* is not supported and does not work. IPython<0.10 was not
tested (not installable by pip).

69
docs/source/usage/shell-prompts.rst
View File

@ -2,14 +2,67 @@
Shell prompts Shell prompts
************* *************
bash Bash prompt
---- ===========
zsh Add the following line to your :file:`bashrc`, where ``{repository_root}`` is
--- the absolute path to your Powerline installation directory:
fish .. code-block:: bash
----
IPython . {repository_root}/powerline/bindings/bash/powerline.sh
-------
Zsh prompt
==========
Add the following line to your :file:`zshrc`, where ``{repository_root}`` is the
absolute path to your Powerline installation directory:
.. code-block:: bash
. {repository_root}/powerline/bindings/zsh/powerline.zsh
Fish prompt
===========
Add the following line to your :file:`config.fish`, where ``{repository_root}``
is the absolute path to your Powerline installation directory:
.. code-block:: bash
set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
powerline-setup
.. _tmux-statusline:
Busybox (ash), mksh and dash prompt
=====================================
After launching busybox run the following command:
.. code-block:: bash
. {repository_root}/powerline/bindings/shell/powerline.sh
Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the
following in ``~/.profile``:
.. code-block:: bash
if test "x$0" != "x${0#dash}" ; then
export ENV={repository_root}/powerline/bindings/shell/powerline.sh
fi
.. note::
Dash users that already have ``$ENV`` defined should either put the ``.
…/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which
will source (using ``.`` command) both former ``$ENV`` file and
:file:`powerline.sh` files and set ``$ENV`` to the path of this new file.
.. warning::
Job count is using some weird hack that uses signals and temporary files for
interprocess communication. It may be wrong sometimes. Not the case in mksh.
.. warning::
Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in
busybox 1.22.1 when using :file:`powerline.sh` script.

63
docs/source/usage/wm-widgets.rst
View File

@ -2,8 +2,63 @@
Window manager widgets Window manager widgets
********************** **********************
Awesome Awesome widget
------- ==============
Qtile .. note:: Powerline currently only supports awesome 3.5.
-----
.. note:: The Powerline widget will spawn a shell script that runs in the
background and updates the statusline with ``awesome-client``.
Add the following to your :file:`rc.lua`, where ``{repository_root}`` is the
absolute path to your Powerline installation directory:
.. code-block:: lua
package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
require('powerline')
Then add the ``powerline_widget`` to your ``wibox``:
.. code-block:: lua
right_layout:add(powerline_widget)
Qtile widget
============
Add the following to your :file:`~/.config/qtile/config.py`:
.. code-block:: python
from powerline.bindings.qtile.widget import Powerline
screens = [
Screen(
top=bar.Bar([
# ...
Powerline(timeout=2),
# ...
],
),
),
]
I3 bar
======
.. note:: Until the patch is done in i3, you will need a custom ``i3bar`` build
called ``i3bgbar``. The source is available `here
<https://github.com/S0lll0s/i3bgbar>`_.
Add the following to your :file:`~/.i3/config`::
bar {
i3bar_command i3bgbar
status_command python /path/to/powerline/bindings/i3/powerline-i3.py
font pango:PowerlineFont 12
}
where ``i3bgbar`` may be replaced with the path to the custom i3bar binary and
``PowerlineFont`` is any system font with powerline support.