Adding upstream version 2.8.1.upstream/2.8.1upstream

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

6 files changed, 736 insertions, 0 deletions

diff --git a/docs/source/develop.rst b/docs/source/develop.rst
new file mode 100644
index 0000000..bf45498
--- /dev/null
+++ b/docs/source/develop.rst
@@ -0,0 +1,13 @@
+***************
+Developer guide
+***************
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   develop/segments
+   develop/listers
+   develop/local-themes
+   develop/extensions
+   develop/tips-and-tricks
diff --git a/docs/source/develop/extensions.rst b/docs/source/develop/extensions.rst
new file mode 100644
index 0000000..2ddf223
--- /dev/null
+++ b/docs/source/develop/extensions.rst
@@ -0,0 +1,47 @@
+********************************
+Creating new powerline extension
+********************************
+
+Powerline extension is a code that tells powerline how to highlight and display 
+segments in some set of applications. Specifically this means
+
+#. Creating a :py:class:`powerline.Powerline` subclass that knows how to obtain 
+   :ref:`local configuration overrides <local-configuration-overrides>`. It also 
+   knows how to load local themes, but not when to apply them.
+
+   Instance of this class is the only instance that interacts directly with 
+   bindings code, so it has a proxy :py:meth:`powerline.Powerline.render` and 
+   :py:meth:`powerline.Powerline.shutdown` methods and other methods which may 
+   be useful for bindings.
+
+   This subclass must be placed directly in :file:`powerline` directory (e.g. in 
+   :file:`powerline/vim.py`) and named like ``VimPowerline`` (version of the 
+   file name without directory and extension and first capital letter 
+   + ``Powerline``). There is no technical reason for naming classes like this.
+#. Creating a :py:class:`powerline.renderer.Renderer` subclass that knows how to 
+   highlight a segment or reset highlighting to the default value (only makes 
+   sense in prompts). It is also responsible for selecting local themes and 
+   computing text width.
+
+   This subclass must be placed directly in :file:`powerline/renderers` 
+   directory (for powerline extensions developed for a set of applications use 
+   :file:`powerline/renderers/{ext}/*.py`) and named like ``ExtRenderer`` or 
+   ``AppPromptRenderer``. For technical reasons the class itself must be 
+   referenced in ``renderer`` module attribute thus allowing only one renderer 
+   per one module.
+#. Creating an extension bindings. These are to be placed in 
+   :file:`powerline/bindings/{ext}` and may contain virtually anything which may 
+   be required for powerline to work inside given applications, assuming it does 
+   not fit in other places.
+
+Powerline class
+===============
+
+.. autoclass:: powerline.Powerline
+   :members:
+
+Renderer class
+==============
+
+.. autoclass:: powerline.renderer.Renderer
+   :members:
diff --git a/docs/source/develop/listers.rst b/docs/source/develop/listers.rst
new file mode 100644
index 0000000..e779704
--- /dev/null
+++ b/docs/source/develop/listers.rst
@@ -0,0 +1,49 @@
+.. _dev-listers:
+
+***************
+Writing listers
+***************
+
+Listers provide a way to show some segments multiple times: once per each entity 
+(buffer, tabpage, etc) lister knows. They are functions which receive the 
+following arguments:
+
+``pl``
+    A :py:class:`powerline.PowerlineLogger` class instance. It must be used for 
+    logging.
+
+``segment_info``
+    Base segment info dictionary. Lister function or class must have 
+    ``powerline_requires_segment_info`` to receive this argument.
+
+    .. warning::
+        Listers are close to useless if they do not have access to this 
+        argument.
+
+    Refer to :ref:`segment_info detailed description <dev-segments-info>` for 
+    further details.
+
+``draw_inner_divider``
+    If False (default) soft dividers between segments in the listed group will 
+    not be drawn regardless of actual segment settings. If True they will be 
+    drawn, again regardless of actual segment settings. Set it to ``None`` in 
+    order to respect segment settings.
+
+And also any other argument(s) specified by user in :ref:`args key 
+<config-themes-seg-args>` (no additional arguments by default).
+
+Listers must return a sequence of pairs. First item in the pair must contain 
+a ``segment_info`` dictionary specific to one of the listed entities.
+
+Second item must contain another dictionary: it will be used to modify the 
+resulting segment. In addition to :ref:`usual keys that describe segment 
+<dev-segments-segment>` the following keys may be present (it is advised that 
+*only* the following keys will be used):
+
+``priority_multiplier``
+    Value (usually a ``float``) used to multiply segment priority. It is useful 
+    for finer-grained controlling which segments disappear first: e.g. when 
+    listing tab pages make first disappear directory names of the tabpages which 
+    are most far away from current tabpage, then (when all directory names 
+    disappeared) buffer names. Check out existing listers implementation in 
+    :file:`powerline/listers/vim.py`.
diff --git a/docs/source/develop/local-themes.rst b/docs/source/develop/local-themes.rst
new file mode 100644
index 0000000..959e1c4
--- /dev/null
+++ b/docs/source/develop/local-themes.rst
@@ -0,0 +1,59 @@
+************
+Local themes
+************
+
+From the user point of view local themes are the regular themes with a specific 
+scope where they are applied (i.e. specific vim window or specific kind of 
+prompt). Used themes are defined in :ref:`local_themes key 
+<config-ext-local_themes>`.
+
+Vim local themes
+================
+
+Vim is the only available extension that has a wide variaty of options for local 
+themes. It is the only extension where local theme key refers to a function as 
+described in :ref:`local_themes value documentation <config-ext-local_themes>`. 
+
+This function always takes a single value named ``matcher_info`` which is the 
+same dictionary as :ref:`segment_info dictionary <dev-segment_info-vim>`. Unlike 
+segments it takes this single argument as a *positional* argument, not as 
+a keyword one.
+
+Matcher function should return a boolean value: ``True`` if theme applies for 
+the given ``matcher_info`` dictionary or ``False`` if it is not. When one of the 
+matcher functions returns ``True`` powerline takes the corresponding theme at 
+uses it for the given window. Matchers are not tested in any particular order.
+
+In addition to :ref:`local_themes configuration key <config-ext-local_themes>` 
+developer of some plugin which wishes to support powerline without including his 
+code in powerline tree may use 
+:py:meth:`powerline.vim.VimPowerline.add_local_theme` method. It accepts two 
+arguments: matcher name (same as in :ref:`local_themes 
+<config-ext-local_themes>`) and dictionary with theme. This dictionary is merged 
+with :ref:`top theme <config-ext-top_theme>` and 
+:file:`powerline/themes/vim/__main__.json`. Note that if user already specified 
+the matcher in his configuration file ``KeyError`` is raised.
+
+Other local themes
+==================
+
+Except for Vim only IPython and shells have local themes. Unlike Vim these 
+themes are names with no special meaning (they do not refer to or cause loading 
+of any Python functions):
+
++---------+------------+-------------------------------------------------------+
+|Extension|Theme name  |Description                                            |
++---------+------------+-------------------------------------------------------+
+|Shell    |continuation|Shown for unfinished command (unclosed quote,          |
+|         |            |unfinished cycle).                                     |
+|         +------------+-------------------------------------------------------+
+|         |select      |Shown for ``select`` command available in some shells. |
++---------+------------+-------------------------------------------------------+
+|IPython  |in2         |Continuation prompt: shown for unfinished (multiline)  |
+|         |            |expression, unfinished class or function definition.   |
+|         +------------+-------------------------------------------------------+
+|         |out         |Displayed before the result.                           |
+|         +------------+-------------------------------------------------------+
+|         |rewrite     |Displayed before the actually executed code when       |
+|         |            |``autorewrite`` IPython feature is enabled.            |
++---------+------------+-------------------------------------------------------+
diff --git a/docs/source/develop/segments.rst b/docs/source/develop/segments.rst
new file mode 100644
index 0000000..543ddd5
--- /dev/null
+++ b/docs/source/develop/segments.rst
@@ -0,0 +1,547 @@
+.. _dev-segments:
+
+****************
+Writing segments
+****************
+
+Each powerline segment is a callable object. It is supposed to be either 
+a Python function or :py:class:`powerline.segments.Segment` class. As a callable 
+object it should receive the following arguments:
+
+.. note:: All received arguments are keyword arguments.
+
+``pl``
+    A :py:class:`powerline.PowerlineLogger` instance. It must be used every time 
+    something needs to be logged.
+
+``segment_info``
+    A dictionary. It is only received if callable has 
+    ``powerline_requires_segment_info`` attribute.
+
+    Refer to :ref:`segment_info detailed description <dev-segments-info>` for 
+    further details.
+
+``create_watcher``
+    Function that will create filesystem watcher once called. Which watcher will 
+    be created exactly is controlled by :ref:`watcher configuration option 
+    <config-common-watcher>`.
+
+And also any other argument(s) specified by user in :ref:`args key 
+<config-themes-seg-args>` (no additional arguments by default).
+
+.. note::
+    For powerline-lint to work properly the following things may be needed:
+
+    #. If segment is a :py:class:`powerline.segments.Segment` instance and used 
+       arguments are scattered over multiple methods 
+       :py:meth:`powerline.segments.Segment.argspecobjs` should be overridden in 
+       subclass to tell powerline-lint which objects should be inspected for 
+       arguments.
+    #. If segment takes some arguments that are never listed, but accessed via 
+       ``kwargs.get()`` or previous function cannot be used for whatever reason 
+       :py:meth:`powerline.segments.Segment.additional_args` should be 
+       overridden in subclass.
+    #. If user is expected to use one :ref:`name <config-themes-seg-name>` for 
+       multiple segments which cannot be linked to the segment function 
+       automatically by powerline-lint (e.g. because there are no instances of 
+       the segments in question in the default configuration) 
+       :py:func:`powerline.lint.checks.register_common_name` function should be 
+       used.
+
+Object representing segment may have the following attributes used by 
+powerline:
+
+``powerline_requires_segment_info``
+    This attribute controls whether segment will receive ``segment_info`` 
+    argument: if it is present argument will be received.
+
+``powerline_requires_filesystem_watcher``
+    This attribute controls whether segment will receive ``create_watcher`` 
+    argument: if it is present argument will be received.
+
+``powerline_segment_datas``
+    This attribute must be a dictionary containing ``top_theme: segment_data`` 
+    mapping where ``top_theme`` is any theme name (it is expected that all of
+    the names from :ref:`top-level themes list <config-top_themes-list>` are 
+    present) and ``segment_data`` is a dictionary like the one that is contained 
+    inside :ref:`segment_data dictionary in configuration 
+    <config-themes-segment_data>`. This attribute should be used to specify 
+    default theme-specific values for *third-party* segments: powerline 
+    theme-specific values go directly to :ref:`top-level themes 
+    <config-themes>`.
+
+.. _dev-segments-startup:
+
+``startup``
+    This attribute must be a callable which accepts the following keyword 
+    arguments:
+
+    * ``pl``: :py:class:`powerline.PowerlineLogger` instance which is to be used 
+      for logging.
+    * ``shutdown_event``: :py:class:`Event` object which will be set when 
+      powerline will be shut down.
+    * Any arguments found in user configuration for the given segment (i.e. 
+      :ref:`args key <config-themes-seg-args>`).
+
+    This function is called at powerline startup when using long-running 
+    processes (e.g. powerline in vim, in zsh with libzpython, in ipython or in 
+    powerline daemon) and not called when ``powerline-render`` executable is 
+    used (more specific: when :py:class:`powerline.Powerline` constructor 
+    received true ``run_once`` argument).
+
+.. _dev-segments-shutdown:
+
+``shutdown``
+    This attribute must be a callable that accepts no arguments and shuts down 
+    threads and frees any other resources allocated in ``startup`` method of the 
+    segment in question.
+
+    This function is not called when ``startup`` method is not called.
+
+.. _dev-segments-expand:
+
+``expand``
+    This attribute must be a callable that accepts the following keyword 
+    arguments:
+
+    * ``pl``: :py:class:`powerline.PowerlineLogger` instance which is to be used 
+      for logging.
+    * ``amount``: integer number representing amount of display cells result 
+      must occupy.
+
+      .. warning::
+         “Amount of display cells” is *not* number of Unicode codepoints, string 
+         length, or byte count. It is suggested that this function should look 
+         something like ``return (' ' * amount) + segment['contents']`` where 
+         ``' '`` may be replaced with anything that is known to occupy exactly 
+         one display cell.
+    * ``segment``: :ref:`segment dictionary <dev-segments-segment>`.
+    * Any arguments found in user configuration for the given segment (i.e. 
+      :ref:`args key <config-themes-seg-args>`).
+
+    It must return new value of :ref:`contents <dev-segments-seg-contents>` key.
+
+.. _dev-segments-truncate:
+
+``truncate``
+    Like :ref:`expand function <dev-segments-expand>`, but for truncating 
+    segments. Here ``amount`` means the number of display cells which must be 
+    freed.
+
+    This function is called for all segments before powerline starts purging 
+    them to free space.
+
+This callable object should may return either a string (``unicode`` in Python2 
+or ``str`` in Python3, *not* ``str`` in Python2 or ``bytes`` in Python3) object 
+or a list of dictionaries. String object is a short form of the following return 
+value:
+
+.. code-block:: python
+
+    [{
+        'contents': original_return,
+        'highlight_groups': [segment_name],
+    }]
+
+.. _dev-segments-return:
+
+Returned list is a list of segments treated independently, except for 
+:ref:`draw_inner_divider key <dev-segments-draw_inner_divider>`.
+
+All keys in segments returned by the function override those obtained from 
+:ref:`configuration <config-themes-segments>` and have the same meaning.
+
+Detailed description of used dictionary keys:
+
+.. _dev-segments-contents:
+
+``contents``
+    Text displayed by segment. Should be a ``unicode`` (Python2) or ``str`` 
+    (Python3) instance.
+
+``literal_contents``
+    Text that needs to be output literally (i.e. without passing through 
+    :py:meth:`powerline.renderer.strwidth` to determine length, through
+    :py:meth:`powerline.renderer.escape` to escape special characters and 
+    through :py:meth:`powerline.renderer.hl` to highlight it). Should be a tuple
+    ``(contents_length, contents)`` where ``contents_length`` is an integer and 
+    ``contents`` is a ``unicode`` (Python2) or ``str`` (Python3) instance.
+
+    If this key is present and its second value is true then other contents keys 
+    (:ref:`contents <dev-segments-contents>`, :ref:`after
+    <config-themes-seg-after>`, :ref:`before <config-themes-seg-before>`) will 
+    be ignored.
+
+    .. note::
+       If target is inclusion of the segment in powerline upstream all segment 
+       functions that output *only* subsegments with ``literal_contents`` key
+       must contain the following string in documentation::
+
+           No highlight groups are used (literal segment).
+
+       String must be present on the separate line.
+
+.. _dev-segments-draw_inner_divider:
+
+``draw_hard_divider``, ``draw_soft_divider``, ``draw_inner_divider``
+    Determines whether given divider should be drawn. All have the same meaning 
+    as :ref:`the similar keys in configuration <config-themes-seg-draw_divider>` 
+    (:ref:`draw_inner_divider <config-themes-seg-draw_inner_divider>`).
+
+.. _dev-segments-highlight_groups:
+
+``highlight_groups``
+    Determines segment highlighting. Refer to :ref:`themes documentation 
+    <config-themes-seg-highlight_groups>` for more details.
+
+    Defaults to the name of the segment.
+
+    .. note::
+       If target is inclusion of the segment in powerline upstream all used 
+       highlighting groups must be specified in the segment documentation in the 
+       form::
+
+           Highlight groups used: ``g1``[ or ``g2``]*[, ``g3`` (gradient)[ or ``g4``]*]*.
+
+       I.e. use::
+
+           Highlight groups used: ``foo_gradient`` (gradient) or ``foo``, ``bar``.
+
+       to specify that the segment uses *either* ``foo_gradient`` group or 
+       ``foo`` group *and* ``bar`` group meaning that ``powerline-lint`` will 
+       check that at least one of the first two groups is defined (and if 
+       ``foo_gradient`` is defined it must use at least one gradient color) and 
+       third group is defined as well.
+
+       All groups must be specified on one line.
+
+``divider_highlight_group``
+    Determines segment divider highlight group. Only applicable for soft 
+    dividers: colors for hard dividers are determined by colors of adjacent 
+    segments.
+
+    .. note::
+       If target is inclusion of the segment in powerline upstream used divider 
+       highlight group must be specified in the segment documentation in the 
+       form::
+
+            Divider highlight group used: ``group``.
+
+        This text must not wrap and all divider highlight group names are 
+        supposed to end with ``:divider``: e.g. ``cwd:divider``.
+
+``gradient_level``
+    First and the only key that may not be specified in user configuration. It 
+    determines which color should be used for this segment when one of the 
+    highlighting groups specified by :ref:`highlight_groups 
+    <dev-segments-highlight_groups>` was defined to use the color gradient.
+
+    This key may have any value from 0 to 100 inclusive, value is supposed to be 
+    an ``int`` or ``float`` instance.
+
+    No error occurs if segment has this key, but no used highlight groups use 
+    gradient color.
+
+``_*``
+    Keys starting with underscore are reserved for powerline and must not be 
+    returned.
+
+``__*``
+    Keys starting with two underscores are reserved for the segment functions, 
+    specifically for :ref:`expand function <dev-segments-expand>`.
+
+.. _dev-segments-segment:
+
+Segment dictionary
+==================
+
+Segment dictionary contains the following keys:
+
+* All keys returned by segment function (if it was used).
+
+* All of the following keys:
+
+  ``name``
+    Segment name: value of the :ref:`name key <config-themes-seg-name>` or 
+    function name (last component of the :ref:`function key 
+    <config-themes-seg-function>`). May be ``None``.
+
+  ``type``
+    :ref:`Segment type <config-themes-seg-type>`. Always represents actual type 
+    and is never ``None``.
+
+  ``highlight_groups``, ``divider_highlight_group``
+    Used highlight groups. May be ``None``.
+
+  ``highlight_group_prefix``
+    If this key is present then given prefix will be prepended to each highlight 
+    group (both regular and divider) used by this segment in a form 
+    ``{prefix}:{group}`` (note the colon). This key is mostly useful for 
+    :ref:`segment listers <dev-listers>`.
+
+  .. _dev-segments-seg-around:
+
+  ``before``, ``after``
+    Value of :ref:`before <config-themes-seg-before>` or :ref:`after 
+    <config-themes-seg-after>` configuration options. May be ``None`` as well as 
+    an empty string.
+
+  ``contents_func``
+    Function used to get segment contents. May be ``None``.
+
+  .. _dev-segments-seg-contents:
+
+  ``contents``
+    Actual segment contents, excluding dividers and :ref:`before/after 
+    <dev-segments-seg-around>`. May be ``None``.
+
+  ``priority``
+    :ref:`Segment priority <config-themes-seg-priority>`. May be ``None`` for no 
+    priority (such segments are always shown).
+
+  ``draw_soft_divider``, ``draw_hard_divider``, ``draw_inner_divider``
+    :ref:`Divider control flags <dev-segments-draw_inner_divider>`.
+
+  ``side``
+    Segment side: ``right`` or ``left``.
+
+  ``display_condition``
+    Contains function that takes three position parameters: 
+    :py:class:`powerline.PowerlineLogger` instance, :ref:`segment_info 
+    <dev-segments-info>` dictionary and current mode and returns either ``True`` 
+    or ``False`` to indicate whether particular segment should be processed.
+
+    This key is constructed based on :ref:`exclude_/include_modes keys 
+    <config-themes-seg-exclude_modes>` and :ref:`exclude_/include_function keys 
+    <config-themes-seg-exclude_function>`.
+
+  ``width``, ``align``
+    :ref:`Width and align options <config-themes-seg-align>`. May be ``None``.
+
+  ``expand``, ``truncate``
+    Partially applied :ref:`expand <dev-segments-expand>` or :ref:`truncate 
+    <dev-segments-truncate>` function. Accepts ``pl``, ``amount`` and 
+    ``segment`` positional parameters, keyword parameters from :ref:`args 
+    <config-themes-seg-args>` key were applied.
+
+  ``startup``
+    Partially applied :ref:`startup function <dev-segments-startup>`. Accepts 
+    ``pl`` and ``shutdown_event`` positional parameters, keyword parameters from 
+    :ref:`args <config-themes-seg-args>` key were applied.
+
+  ``shutdown``
+    :ref:`Shutdown function <dev-segments-shutdown>`. Accepts no argument.
+
+Segments layout
+===============
+
+Powerline segments are all located in one of the ``powerline.segments`` 
+submodules. For extension-specific segments ``powerline.segments.{ext}`` module 
+should be used (e.g. ``powerline.segments.shell``), for extension-agnostic there 
+is ``powerline.segments.common``.
+
+Plugin-specific segments (currently only those that are specific to vim plugins) 
+should live in ``powerline.segments.{ext}.plugin.{plugin_name}``: e.g. 
+``powerline.segments.vim.plugin.gundo``.
+
+.. _dev-segments-info:
+
+Segment information used in various extensions
+==============================================
+
+Each ``segment_info`` value should be a dictionary with at least the following 
+keys:
+
+``environ``
+    Current environment, may be an alias to ``os.environ``. Is guaranteed to 
+    have ``__getitem__`` and ``get`` methods and nothing more.
+
+    .. warning::
+       ``os.environ`` must not ever be used:
+
+       * If segment is run in the daemon this way it will get daemon’s 
+         environment which is not correct.
+       * If segment is run in Vim or in zsh with libzpython ``os.environ`` will 
+         contain Vim or zsh environ *at the moment Python interpreter was 
+         loaded*.
+
+``getcwd``
+    Function that returns current working directory being called with no 
+    arguments. ``os.getcwd`` must not be used for the same reasons the use of 
+    ``os.environ`` is forbidden, except that current working directory is valid 
+    in Vim and zsh (but not in daemon).
+
+``home``
+    Current home directory. May be false.
+
+.. _dev-segment_info-vim:
+
+Vim
+---
+
+Vim ``segment_info`` argument is a dictionary with the following keys:
+
+``window``
+    ``vim.Window`` object. ``vim.current.window`` or ``vim.windows[number - 1]`` 
+    may be used to obtain such object. May be a false object, in which case any 
+    of this object’s properties must not be used.
+
+``winnr``
+    Window number. Same as ``segment_info['window'].number`` *assuming* Vim is 
+    new enough for ``vim.Window`` object to have ``number`` attribute.
+
+``window_id``
+    Internal powerline window id, unique for each newly created window. It is 
+    safe to assume that this ID is hashable and supports equality comparison, 
+    but no other assumptions about it should be used. Currently uses integer 
+    numbers incremented each time window is created.
+
+``buffer``
+    ``vim.Buffer`` object. One may be obtained using ``vim.current.buffer``, 
+    ``segment_info['window'].buffer`` or ``vim.buffers[some_number]``. Note that 
+    in the latter case depending on vim version ``some_number`` may be ``bufnr`` 
+    or the internal Vim buffer index which is *not* buffer number. For this 
+    reason to get ``vim.Buffer`` object other then stored in ``segment_info`` 
+    dictionary iteration over ``vim.buffers`` and checking their ``number`` 
+    attributes should be performed.
+
+``bufnr``
+    Buffer number.
+
+``tabpage``
+    ``vim.Tabpage`` object. One may be obtained using ``vim.current.tabpage`` or 
+    ``vim.tabpages[number - 1]``. May be a false object, in which case no 
+    object’s properties can be used.
+
+``tabnr``
+    Tabpage number.
+
+``mode``
+    Current mode.
+
+``encoding``
+    Value of ``&encoding`` from the time when powerline was initialized. It 
+    should be used to convert return values.
+
+.. note::
+   Segment generally should not assume that it is run for the current window, 
+   current buffer or current tabpage. “Current window” and “current buffer” 
+   restrictions may be ignored if ``window_cached`` decorator is used, “current 
+   tabpage” restriction may be safely ignored if segment is not supposed to be 
+   used in tabline.
+
+.. warning::
+   Powerline is being tested with vim-7.0.112 (some minor sanity check) and 
+   latest Vim. This means that most of the functionality like 
+   ``vim.Window.number``, ``vim.*.vars``, ``vim.*.options`` or even ``dir(vim 
+   object)`` should be avoided in segments that want to be included in the 
+   upstream.
+
+Shell
+-----
+
+``args``
+    Parsed shell arguments: a ``argparse.Namespace`` object. Check out 
+    ``powerline-render --help`` for the list of all available arguments. 
+    Currently it is expected to contain at least the following attributes:
+
+    ``last_exit_code``
+        Exit code returned by last shell command. Is either one integer, 
+        ``sig{name}`` or ``sig{name}+core`` (latter two are only seen in ``rc`` 
+        shell).
+
+    ``last_pipe_status``
+        List of exit codes returned by last programs in the pipe or some false 
+        object. Only available in ``zsh`` and ``rc``. Is a list of either 
+        integers, ``sig{name}`` or ``sig{name}+core`` (latter two are only seen 
+        in ``rc`` shell).
+
+    ``jobnum``
+        Number of background jobs.
+
+    ``renderer_arg``
+        Dictionary containing some keys that are additional arguments used by 
+        shell bindings. *This attribute must not be used directly*: all 
+        arguments from this dictionary are merged with ``segment_info`` 
+        dictionary. Known to have at least the following keys:
+
+        ``client_id``
+            Identifier unique to one shell instance. Is used to record instance 
+            state by powerline daemon. In tmux this is the same as :ref:`pane_id 
+            <dev-seginfo-shell-renarg-pane_id>`.
+
+            It is not guaranteed that existing client ID will not be retaken 
+            when old shell with this ID quit: usually process PID is used as 
+            a client ID.
+
+            It is also not guaranteed that client ID will be process PID, number 
+            or something else at all. It is guaranteed though that client ID 
+            will be some hashable object which supports equality comparison.
+
+        ``local_theme``
+            Local theme that will be used by shell. One should not rely on the 
+            existence of this key.
+
+        .. _dev-seginfo-shell-renarg-pane_id:
+
+        ``pane_id``
+            Identifier unique to each tmux pane. Is always an integer, optional. 
+            Obtained by using ``tmux display -p '#D'``, then all leading spaces 
+            and per cent signs are stripped and the result is converted into an 
+            integer.
+
+        Other keys, if any, are specific to segments.
+
+Ipython
+-------
+
+``ipython``
+    Some object which has ``prompt_count`` attribute. Currently it is guaranteed 
+    to have only this attribute.
+
+    Attribute ``prompt_count`` contains the so-called “history count” 
+    (equivalent to ``\N`` in ``in_template``).
+
+Pdb
+---
+
+``pdb``
+    Currently active :py:class:`pdb.Pdb` instance.
+
+``curframe``
+    Frame which will be run next. Note: due to the existence of 
+    :py:func:`powerline.listers.pdb.frame_lister` one must not use 
+    ``segment_info['pdb'].curframe``.
+
+``initial_stack_length``
+    Equal to the length of :py:attr:`pdb.Pdb.stack` at the first invocation of 
+    the prompt decremented by one.
+
+i3wm
+----
+
+``mode``
+    Currently active i3 mode (as a string).
+
+``output``
+    ``xrandr`` output name currently drawing to. Currently only available
+    in lemonbar bindings.
+
+``workspace``
+    dictionary containing the workspace name under the key ``"name"`` and 
+    boolean values for the ``"visible"``, ``"urgent"`` and ``"focused"`` 
+    keys, indicating the state of the workspace. Currently only provided by 
+    the :py:func:`powerline.listers.i3wm.workspace_lister` lister.
+
+Segment class
+=============
+
+.. autoclass:: powerline.segments.Segment
+   :members:
+
+PowerlineLogger class
+=====================
+
+.. autoclass:: powerline.PowerlineLogger
+   :members:
+   :undoc-members:
diff --git a/docs/source/develop/tips-and-tricks.rst b/docs/source/develop/tips-and-tricks.rst
new file mode 100644
index 0000000..c850659
--- /dev/null
+++ b/docs/source/develop/tips-and-tricks.rst
@@ -0,0 +1,21 @@
+****************************************
+Tips and tricks for powerline developers
+****************************************
+
+Profiling powerline in Vim
+==========================
+
+Given that current directory is the root of the powerline repository the 
+following command may be used:
+
+.. code-block:: sh
+
+    vim --cmd 'let g:powerline_pyeval="powerline#debug#profile_pyeval"' \
+        --cmd 'set rtp=powerline/bindings/vim' \
+        -c 'runtime! plugin/powerline.vim' \
+        {other arguments if needed}
+
+After some time run ``:WriteProfiling {filename}`` Vim command. Currently this 
+only works with recent Vim and python-2*. It should be easy to modify 
+:file:`powerline/bindings/vim/autoload/powerline/debug.vim` to suit other 
+needs.