diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 83a218e6..55cb28ad 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -96,6 +96,8 @@ segments that you may want to customize right away: } }, +.. _config-main: + Main configuration ================== @@ -111,7 +113,7 @@ Common configuration Common configuration is a subdictionary that is a value of ``common`` key in :file:`powerline/config.json` file. -.. _config-term_24bit_colors: +.. _config-common-term_24bit_colors: ``term_24bit_colors`` Defines whether to output cterm indices (8-bit) or RGB colors (24-bit) @@ -152,7 +154,14 @@ Common configuration is a subdictionary that is a value of ``ext`` key in .. _config-ext-local_themes: Defines themes used when certain conditions are met, e.g. for - buffer-specific statuslines in vim. Requires a custom matcher and theme. + 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 ================= @@ -178,6 +187,8 @@ Color definitions * A list of cterm color indicies. * A list of hex color strings. +.. _config-colorschemes: + Colorschemes ============ @@ -186,7 +197,7 @@ Colorschemes ``name`` Name of the colorscheme. -.. _config-colorscheme-groups: +.. _config-colorschemes-groups: ``groups`` Segment highlighting groups, consisting of a dict where the key is the @@ -220,7 +231,9 @@ Colorschemes ``groups`` Segment highlighting groups for this mode. Same syntax as the main - :ref:`groups ` option. + :ref:`groups ` option. + +.. _config-themes: Themes ====== diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst index ad099318..cffd2a7c 100644 --- a/docs/source/installation/linux.rst +++ b/docs/source/installation/linux.rst @@ -21,7 +21,7 @@ follow the installation guide below: Plugin installation =================== -1. Install Python 3.3+ or Python 2.7. +1. Install Python 3.2+ or Python 2.7. 2. Install Powerline using the following command:: pip install --user git+git://github.com/Lokaltog/powerline diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 18d520cd..a550f32e 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -31,8 +31,8 @@ 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. +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 diff --git a/powerline/__init__.py b/powerline/__init__.py index 5296cde9..434310e5 100644 --- a/powerline/__init__.py +++ b/powerline/__init__.py @@ -20,6 +20,19 @@ def load_json_config(search_paths, config_file): class Powerline(object): + '''Main powerline class, entrance point for all powerline uses. Sets + powerline up and loads the configuration. + + :param str ext: + extension used. Determines where configuration files will + searched and what renderer module will be used. Affected: used ``ext`` + dictionary from :file:`powerline/config.json`, location of themes and + colorschemes, render module (``powerline.renders.{ext}``). + :param str renderer_module: + Overrides renderer module (defaults to ``ext``). Should be the name of + the package imported like this: ``powerline.renders.{render_module}``. + ''' + def __init__(self, ext, renderer_module=None): self.config_paths = self.get_config_paths() @@ -58,27 +71,71 @@ class Powerline(object): self.renderer = Renderer(theme_config, local_themes, theme_kwargs, colorscheme, **options) def get_config_paths(self): + '''Get configuration paths. + + :return: list of paths + ''' config_home = os.environ.get('XDG_CONFIG_HOME', os.path.join(os.path.expanduser('~'), '.config')) config_path = os.path.join(config_home, 'powerline') plugin_path = os.path.join(os.path.realpath(os.path.dirname(__file__)), 'config_files') return [config_path, plugin_path] def load_theme_config(self, name): + '''Get theme configuration. + + :param str name: + Name of the theme to load. + + :return: dictionary with :ref:`theme configuration ` + ''' return load_json_config(self.config_paths, os.path.join('themes', self.ext, name)) def load_main_config(self): + '''Get top-level configuration. + + :return: dictionary with :ref:`top-level configuration `. + ''' return load_json_config(self.config_paths, 'config') def load_colorscheme_config(self, name): + '''Get colorscheme. + + :param str name: + Name of the colorscheme to load. + + :return: dictionary with :ref:`colorscheme configuration `. + ''' return load_json_config(self.config_paths, os.path.join('colorschemes', self.ext, name)) def load_colors_config(self): + '''Get colorscheme. + + :return: dictionary with :ref:`colors configuration `. + ''' return load_json_config(self.config_paths, 'colors') @staticmethod def get_local_themes(local_themes): + '''Get local themes. No-op here, to be overridden in subclasses if + required. + + :param dict local_themes: + Usually accepts ``{matcher_name : theme_name}``. + + :return: + anything accepted by ``self.renderer.get_theme`` and processable by + ``self.renderer.add_local_theme``. Renderer module is determined by + ``__init__`` arguments, refer to its documentation. + ''' return {} @staticmethod def get_segment_info(): + '''Get information for segments that require ``segment_info`` argument. + To be overridden in subclasses. + + :return: + anything accepted by segments as ``segment_info`` argument. Depends + on the segments used, refer to Powerline subclass documentation. + ''' return None diff --git a/powerline/vim.py b/powerline/vim.py index 968aa510..2e234d97 100644 --- a/powerline/vim.py +++ b/powerline/vim.py @@ -30,12 +30,21 @@ class VimPowerline(Powerline): def add_local_theme(self, key, config): '''Add local themes at runtime (during vim session). - Accepts key as first argument (same as keys in config.json: - ext/*/local_themes) and configuration dictionary as the second (has - format identical to themes/*/*.json) + :param str key: + Matcher name (in format ``{matcher_module}.{module_attribute}`` or + ``{module_attribute}`` if ``{matcher_module}`` is + ``powerline.matchers.vim``). Function pointed by + ``{module_attribute}`` should be hashable and accept a dictionary + with information about current buffer and return boolean value + indicating whether current window matched conditions. See also + :ref:`local_themes key description `. - Returns True if theme was added successfully and False if theme with - the same matcher already exists + :param dict config: + :ref:`Theme ` dictionary. + + :return: + ``True`` if theme was added successfully and ``False`` if theme with + the same matcher already exists. ''' key = self.get_matcher(key) try: