diff --git a/docs/source/configuration-and-customization.rst b/docs/source/configuration-and-customization.rst deleted file mode 100644 index 6d5e8c79..00000000 --- a/docs/source/configuration-and-customization.rst +++ /dev/null @@ -1,15 +0,0 @@ -******************************* -Configuration and customization -******************************* - -Quick setup guide ------------------ - -References ----------- - -.. toctree:: - :glob: - - configuration-reference - segment-reference diff --git a/docs/source/configuration-reference.rst b/docs/source/configuration-reference.rst deleted file mode 100644 index 1e4eef8b..00000000 --- a/docs/source/configuration-reference.rst +++ /dev/null @@ -1,3 +0,0 @@ -*********************** -Configuration reference -*********************** diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..50b39e54 --- /dev/null +++ b/docs/source/configuration.rst @@ -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 ` + :file:`powerline/config.json` +:ref:`Colorschemes ` + :file:`powerline/colorschemes/{name}.json`, + :file:`powerline/colorscheme/__main__.json`, + :file:`powerline/colorschemes/{extension}/{name}.json` +:ref:`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 `. + +.. _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 + `_ 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 diff --git a/docs/source/configuration/local.rst b/docs/source/configuration/local.rst new file mode 100644 index 00000000..d8d55e84 --- /dev/null +++ b/docs/source/configuration/local.rst @@ -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 ` 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. diff --git a/docs/source/configuration/reference.rst b/docs/source/configuration/reference.rst new file mode 100644 index 00000000..b096f922 --- /dev/null +++ b/docs/source/configuration/reference.rst @@ -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 + ` 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 `. 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 + `. + + ``bg`` + Background color. Must be defined in :ref:`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 `. + + ``groups`` + Segment highlighting groups for this mode. Same syntax as the main + :ref:`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 `, + :ref:`args ` (only for function segments), + :ref:`before `, + :ref:`contents ` (only for string segments + if :ref:`name ` is defined), + :ref:`display ` 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 + `. For the :ref:`default 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 ` ``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 `. + + ``string`` + A static string segment where the contents is defined in the + :ref:`contents option `, and the + highlighting group is defined in the :ref:`highlight_group + option `. + + ``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 `. + + ``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``. diff --git a/docs/source/configuration/segments.rst b/docs/source/configuration/segments.rst new file mode 100644 index 00000000..e6e48f36 --- /dev/null +++ b/docs/source/configuration/segments.rst @@ -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 `, 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/* diff --git a/docs/source/segment-reference/common.rst b/docs/source/configuration/segments/common.rst similarity index 100% rename from docs/source/segment-reference/common.rst rename to docs/source/configuration/segments/common.rst diff --git a/docs/source/segment-reference/shell.rst b/docs/source/configuration/segments/shell.rst similarity index 100% rename from docs/source/segment-reference/shell.rst rename to docs/source/configuration/segments/shell.rst diff --git a/docs/source/segment-reference/vim.rst b/docs/source/configuration/segments/vim.rst similarity index 100% rename from docs/source/segment-reference/vim.rst rename to docs/source/configuration/segments/vim.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 5a502249..53e32232 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,7 +9,7 @@ Powerline overview installation usage - configuration-and-customization + configuration troubleshooting tips-and-tricks license-and-credits diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 3696e7c0..b78497a9 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -2,6 +2,53 @@ 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 `_. 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:: Linux diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst index 377770a3..f4df8f40 100644 --- a/docs/source/installation/linux.rst +++ b/docs/source/installation/linux.rst @@ -2,8 +2,28 @@ 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 `_ +* `Arch Linux (AUR), Python 3 version `_ +* Gentoo Live ebuild in `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``. diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst index b44f5529..e2e1c9b8 100644 --- a/docs/source/installation/osx.rst +++ b/docs/source/installation/osx.rst @@ -2,8 +2,41 @@ Installation on OS X ******************** -Requirements ------------- +Python package +============== -Installation ------------- +1. Install a proper Python version (see `issue #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 diff --git a/docs/source/segment-reference.rst b/docs/source/segment-reference.rst deleted file mode 100644 index 83b20b12..00000000 --- a/docs/source/segment-reference.rst +++ /dev/null @@ -1,8 +0,0 @@ -***************** -Segment reference -***************** - -.. toctree:: - :glob: - - segment-reference/* diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 31c5fc80..68bdc399 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -2,7 +2,150 @@ Troubleshooting *************** +System-specific issues +====================== + .. toctree:: Linux OS X + +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 `. +* Alternative: set :ref:`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 `_. 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 `_ 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 ` 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 `_ 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 `_ 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`_. diff --git a/docs/source/troubleshooting/linux.rst b/docs/source/troubleshooting/linux.rst index 70bd739d..ed069d94 100644 --- a/docs/source/troubleshooting/linux.rst +++ b/docs/source/troubleshooting/linux.rst @@ -1,3 +1,21 @@ ************************ 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). diff --git a/docs/source/troubleshooting/osx.rst b/docs/source/troubleshooting/osx.rst index e4fd024b..653a06be 100644 --- a/docs/source/troubleshooting/osx.rst +++ b/docs/source/troubleshooting/osx.rst @@ -1,3 +1,61 @@ *********************** Troubleshooting on OS X *********************** + +I can't see any fancy symbols, what's wrong? +-------------------------------------------- + +* If you're using iTerm2, please update to `this revision + `_ + 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 ` 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 `_ for + a discussion and other possible solutions for this issue. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index a03340bf..d6ee2794 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -2,8 +2,62 @@ 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 ` +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 ------- diff --git a/docs/source/usage/other.rst b/docs/source/usage/other.rst index 40e3b686..d312494c 100644 --- a/docs/source/usage/other.rst +++ b/docs/source/usage/other.rst @@ -2,5 +2,99 @@ 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). diff --git a/docs/source/usage/shell-prompts.rst b/docs/source/usage/shell-prompts.rst index 56da391c..e2dbc1d6 100644 --- a/docs/source/usage/shell-prompts.rst +++ b/docs/source/usage/shell-prompts.rst @@ -2,14 +2,67 @@ 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. diff --git a/docs/source/usage/wm-widgets.rst b/docs/source/usage/wm-widgets.rst index f661199d..5383a2fd 100644 --- a/docs/source/usage/wm-widgets.rst +++ b/docs/source/usage/wm-widgets.rst @@ -2,8 +2,63 @@ 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 + `_. + +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.