Improve documentation

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 <config-colorscheme-groups>` option.
+        :ref:`groups <config-colorschemes-groups>` option.
+
+.. _config-themes:
 
 Themes
 ======

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

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 <config-term_24bit_colors>` 
+You can also enable :ref:`24-bit color support 
-if your terminal emulator supports it.
+<config-common-term_24bit_colors>` if your terminal emulator supports it.
 
 .. table:: Application/terminal emulator feature support matrix
    :name: term-feature-support-matrix

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 <config-themes>`
+		'''
 		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 <config-main>`.
+		'''
 		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 <config-colorschemes>`.
+		'''
 		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 <config-colors>`.
+		'''
 		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

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:
+		:param str key:
-		ext/*/local_themes) and configuration dictionary as the second (has
+			Matcher name (in format ``{matcher_module}.{module_attribute}`` or 
-		format identical to themes/*/*.json)
+			``{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 <config-ext-local_themes>`.
 
-		Returns True if theme was added successfully and False if theme with
+		:param dict config:
-		the same matcher already exists
+			:ref:`Theme <config-themes>` dictionary.
+
+		:return:
+			``True`` if theme was added successfully and ``False`` if theme with 
+			the same matcher already exists.
 		'''
 		key = self.get_matcher(key)
 		try: