diff options
Diffstat (limited to 'docs/source/usage/other.rst')
| -rw-r--r-- | docs/source/usage/other.rst | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/docs/source/usage/other.rst b/docs/source/usage/other.rst new file mode 100644 index 0000000..ff0ccae --- /dev/null +++ b/docs/source/usage/other.rst @@ -0,0 +1,224 @@ +************* +Other plugins +************* + +.. _vim-vimrc: + +Vim statusline +============== + +If installed using pip just add + +.. code-block:: vim + + python from powerline.vim import setup as powerline_setup + python powerline_setup() + python del powerline_setup + +(replace ``python`` with ``python3`` if appropriate) to the :file:`vimrc`. + +.. note:: + Status line will not appear by default when there is only a single window + displayed. Run ``:h 'laststatus'`` in Vim for more information. + +If the repository was just cloned the following line needs to be added to the +:file:`vimrc`: + +.. code-block:: vim + + set rtp+={repository_root}/powerline/bindings/vim + +where ``{repository_root}`` is the absolute path to the Powerline installation +directory (see :ref:`repository root <repository-root>`). + +If pathogen is used and Powerline functionality is not needed outside of Vim +then it is possible to simply add Powerline as a bundle and point the path above +to the Powerline bundle directory, e.g. +:file:`~/.vim/bundle/powerline/powerline/bindings/vim`. + +Vundle and NeoBundle users may instead use + +.. code-block:: vim + + Bundle 'powerline/powerline', {'rtp': 'powerline/bindings/vim/'} + +(NeoBundle users need ``NeoBundle`` in place of ``Bundle``, otherwise setup is +the same). + +Vim-addon-manager setup is even easier because it is not needed to write this +big path or install anything by hand: ``powerline`` can be installed and +activated just like any other plugin using + +.. code-block:: vim + + call vam#ActivateAddons(['powerline']) + +.. warning:: + *Never* install powerline with pathogen/VAM/Vundle/NeoBundle *and* with pip. + If powerline functionality is needed in applications other then Vim then + system-wide installation (in case used OS distribution has powerline + package), pip-only or ``pip install --editable`` kind of installation + performed on the repository installed by Vim plugin manager should be used. + + No issues are accepted in powerline issue tracker for double pip/non-pip + installations, especially if these issues occur after update. + +.. note:: + If supplied :file:`powerline.vim` file is used to load powerline there are + additional configuration variables available: ``g:powerline_pycmd`` and + ``g:powerline_pyeval``. First sets command used to load powerline: expected + values are ``"py"`` and ``"py3"``. Second sets function used in statusline, + expected values are ``"pyeval"`` and ``"py3eval"``. + + If ``g:powerline_pycmd`` is set to the one of the expected values then + ``g:powerline_pyeval`` will be set accordingly. If it is set to some other + value then ``g:powerline_pyeval`` must also be set. Powerline will not check + that Vim is compiled with Python support if ``g:powerline_pycmd`` is set to + an unexpected value. + + These values are to be used to specify the only Python that is to be loaded + if both versions are present: Vim may disable loading one python version if + other was already loaded. They should also be used if two python versions + are able to load simultaneously, but powerline was installed only for + python-3 version. + +Tmux statusline +=============== + +Add the following lines to :file:`.tmux.conf`, where ``{repository_root}`` is +the absolute path to the Powerline installation directory (see :ref:`repository +root <repository-root>`):: + + source "{repository_root}/powerline/bindings/tmux/powerline.conf" + +.. note:: + The availability of the ``powerline-config`` command is required for + powerline support. The location of this script may be specified via + the ``$POWERLINE_CONFIG_COMMAND`` environment variable. + +.. note:: + It is advised to run ``powerline-daemon`` before adding the above line to + tmux.conf. To do so add:: + + run-shell "powerline-daemon -q" + + to :file:`.tmux.conf`. + +.. warning:: + Segments which depend on current working directory (e.g. + :py:func:`powerline.segments.common.vcs.branch`) require also setting up + :ref:`shell bindings <usage-shell>`. It is not required to use powerline + shell prompt, :ref:`components setting <config-ext-components>` allows to + set up only powerline bindings for tmux without altering your prompt. + Without setting up shell bindings powerline will use current working + directory of *tmux server* which is probably not what you need. + + Segments which depend on environment like + :py:func:`powerline.segments.common.env.virtualenv` will not work at all + (i.e. they will use environment of the tmux server), tracking environment + changes is going to slow down shell a lot. + + In any case it is suggested to avoid both kinds of segments in tmux + :ref:`themes <config-themes>` because even support for tracking current + directory is very limited: + + #. It works only in shell. Should you e.g. run Vim and run ``:cd`` there you + will get current working directory from shell. + #. It works only in local shell and requires configuring it. + #. Some shells are not supported at all. + +IPython prompt +============== + +For IPython>=7.0, add the following line to +:file:`~/.ipython/profile_default/ipython_config.py` file in the used profile: + + +.. code-block:: Python + + from powerline.bindings.ipython.since_7 import PowerlinePrompts + c.TerminalInteractiveShell.prompts_class = PowerlinePrompts + +.. note:: + If certain graphical/colored elements are not showing, make sure `c.TerminalInteractiveShell.simple_prompt` + is set to `False` in your config. + Setting ``simple_prompt`` to False after IPython-5.0 is required regardless + of whether you use ``c.InteractiveShellApp.extensions`` setting or + ``c.TerminalInteractiveShell.prompts_class``. But you probably already have + this line because ``simple_prompt`` is set to ``False`` by default and IPython + is not very useful without it. + +For IPython>=5.0 and <7.0 it is suggested to use + +.. code-block:: Python + + from powerline.bindings.ipython.since_5 import PowerlinePrompts + c = get_config() + c.TerminalInteractiveShell.simple_prompt = False + c.TerminalInteractiveShell.prompts_class = PowerlinePrompts + + + +For IPython>=5.0 and <7.0 you may use the below set up, but it is deprecated. +For IPython>=0.11 add the following line to +:file:`~/.ipython/profile_default/ipython_config.py` file in the used profile: + +.. code-block:: Python + + c = get_config() + c.InteractiveShellApp.extensions = [ + 'powerline.bindings.ipython.post_0_11' + ] + +For IPython<0.11 add the following lines to :file:`.ipython/ipy_user_conf.py`: + +.. code-block:: Python + + # top + from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup + + # main() function (assuming ipython was launched without configuration to + # create skeleton ipy_user_conf.py file): + powerline_setup() + + +IPython=0.11* is not supported and does not work. IPython<0.10 was not +tested (not installable by pip). + +.. _pdb-prompt: + +PDB prompt +========== + +To use Powerline with PDB prompt you need to use custom class. Inherit your +class from :py:class:`pdb.Pdb` and decorate it with +:py:func:`powerline.bindings.pdb.use_powerline_prompt`: + +.. code-block:: Python + + import pdb + + from powerline.bindings.pdb import use_powerline_prompt + + @use_powerline_prompt + class MyPdb(pdb.Pdb): + pass + + MyPdb.run('some.code.to.debug()') + +. Alternatively you may use + +.. code-block:: bash + + python -mpowerline.bindings.pdb path/to/script.py + +just like you used ``python -m pdb``. + +.. note: + If you are using Python-2.6 you need to use ``python + -mpowerline.bindings.pdb.__main__``, not what is shown above. + +.. warning: + Using PyPy (not PyPy3) forces ASCII-only prompts. In other cases unicode + characters are allowed, even if you use `pdbpp + <https://pypi.python.org/pypi/pdbpp>`_. |