Restructure docs slightly

The header levels have been switched to correspond more with the Sphinx
suggested standards and the troubleshooting section has been
restructured to make it easier to find solutions. Minor markup changes
and other changes are also included in this commit.

docs/source/configuration.rst

@@ -1,5 +1,6 @@
+*************
 Configuration
-=============
+*************
 
 Powerline is configured with one main configuration file, and with separate 
 configuration files for themes and colorschemes. All configuration files are 
@@ -37,7 +38,7 @@ file. Example:
    colorscheme/theme!
 
 Main configuration
-------------------
+==================
 
 :Location: :file:`powerline/config.json`
 
@@ -46,7 +47,7 @@ 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.
@@ -68,7 +69,7 @@ Common configuration is a subdictionary that is a value of ``common`` key in
     have priority when searching for modules.
 
 Extension-specific configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
 
 Common configuration is a subdictionary that is a value of ``ext`` key in 
 :file:`powerline/config.json` file.
@@ -84,7 +85,7 @@ Common configuration is a subdictionary that is a value of ``ext`` key in
     buffer-specific statuslines in vim. Requires a custom matcher and theme.
 
 Colorschemes
-------------
+============
 
 :Location: :file:`powerline/colorschemes/{extension}/{name}.json`
 
@@ -139,7 +140,7 @@ Colorschemes
         :ref:`groups <config-colorscheme-groups>` option.
 
 Themes
-------
+======
 
 :Location: :file:`powerline/themes/{extension}/{name}.json`
 
@@ -243,7 +244,7 @@ Themes
         *not* included in any modes, *except* for the modes in this list.
 
 Segments
---------
+========
 
 Segments are written in Python, and the default segments provided with 
 Powerline are located in :file:`powerline/segments/{extension}.py`.  

docs/source/fontpatching.rst

@@ -1,7 +1,8 @@
 .. _font-patching:
 
+*************
 Font patching
-=============
+*************
 
 Powerline provides a font patcher for custom glyphs like the segment 
 dividers (arrows), branch symbol, padlock symbol, etc. The font patcher 
@@ -24,7 +25,7 @@ patched versions of some popular programming fonts.
    configuration.
 
 Glyph table
------------
+===========
 
 Powerline stores all special glyphs in the Unicode *Private Use Area* 
 (``U+E000``-``U+F8FF``).
@@ -42,7 +43,7 @@ Code point  Glyph  Description
 ==========  =====  ===========
 
 Usage
------
+=====
 
 The font patcher is located at :file:`powerline/fontpatcher/fontpatcher.py`.  
 It requires Python 2.7 and FontForge compiled with Python bindings to work.
@@ -57,7 +58,7 @@ option to disable font renaming.
    the glyphs manually using a tool like ``gbdfed``.
 
 Linux
-^^^^^
+-----
 
 1. Install fontforge with Python bindings. For Ubuntu users the required 
    package is ``python-fontforge``, for Arch Linux users the required 
@@ -89,7 +90,7 @@ Linux
 6. Open vim and enjoy your new statusline!
 
 OS X
-^^^^
+----
 
 1. Check if you have a FontForge version with Python support by running 
    ``fontforge -version``. You should see something like this::

docs/source/index.rst

@@ -1,8 +1,9 @@
+*********
 Powerline
-=========
+*********
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :glob:
 
    introduction

docs/source/introduction.rst

@@ -1,5 +1,6 @@
+************
 Introduction
-============
+************
 
 This is the next version of Powerline, implemented in Python. It aims to 
 resolve some of the "unresolvable" problems of the vimscript implementation, 
@@ -10,7 +11,7 @@ The project is currently in beta, and most of the functionality in the old
 vimscript project is already implemented.
 
 Screenshots
------------
+===========
 
 **Mode-dependent highlighting**
 
@@ -37,7 +38,7 @@ The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi.
 .. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm
 
 Feature highlights
-------------------
+==================
 
 * **Better performance.** Python performs quite a bit better than vimscript, 
   and by having most of the code in Python instead of vimscript it's also 

docs/source/license-credits.rst

@@ -1,3 +1,7 @@
+*******************
+License and credits
+*******************
+
 License
 =======
 

docs/source/overview.rst

@@ -1,8 +1,9 @@
+********
 Overview
-========
+********
 
 Requirements
-------------
+============
 
 Powerline requires Python 3.3 or Python 2.7 to work.
 
@@ -12,15 +13,15 @@ font or a patched font on your system. See `Font installation`_ for more
 details.
 
 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-python3interp`` flag (``--enable-pythoninterp`` if 
+it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if 
-you want Python 2 support instead). Note that this also requires the related 
+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.
@@ -28,20 +29,20 @@ packages.
 Vim version 7.3.661 or newer is recommended for performance reasons.
 
 Optional dependencies
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
 
 The following Python packages are not required by all segments, but 
-recommended for optimal performance:
+recommended for optimal performance and extra features:
 
 * ``pygit2``
 * ``mercurial``
 * ``psutil``
 
 Installation
-------------
+============
 
 Installing with ``pip``
-^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
 
 To install Powerline system-wide, run the following command as root::
 
@@ -54,7 +55,7 @@ system-wide, install with ``pip install --user`` instead.
    conflict with an unrelated project.
 
 Distribution-specific packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
 
 The following distribution-specific packages are officially supported, and 
 they provide an easy way of installing and upgrading Powerline:
@@ -65,10 +66,10 @@ they provide an easy way of installing and upgrading Powerline:
 .. _font-installation:
 
 Font installation
-^^^^^^^^^^^^^^^^^
+-----------------
 
 Linux
-*****
+^^^^^
 
 If you're running Linux, you may be able to avoid patching your coding font 
 to get the special glyphs required by Powerline. This works by utilizing 
@@ -94,13 +95,13 @@ font (see :ref:`font-patching` for details).
    an issue on GitHub.
 
 OS X and Windows
-****************
+^^^^^^^^^^^^^^^^
 
 You'll have to use a patched font to use the Powerline symbols. See 
 :ref:`font-patching` for details on font patching and pre-patched fonts.
 
 Usage
------
+=====
 
 .. note:: If Powerline is installed somewhere other than Python's 
    site-packages directories (e.g. by having the git repo in your dotfiles 
@@ -108,14 +109,14 @@ Usage
    examples below.
 
 Vim statusline
-^^^^^^^^^^^^^^
+--------------
 
 Regular installation
-********************
+^^^^^^^^^^^^^^^^^^^^
 
 **The recommended way of installing Powerline is as a Python package.**
 You can then enable the vim plugin by adding the following line to your 
-``vimrc``:
+:file:`vimrc`:
 
 .. code-block:: vim
 
@@ -129,40 +130,40 @@ If Powerline is installed somewhere other than Python's site-packages
 directories you'll either have to use a plugin manager like Vundle, or 
 source the vim plugin file with an absolute path to the plugin location.
 
-Add the following line to your ``vimrc``, where ``{path}`` is the path to 
+Add the following line to your :file:`vimrc`, where ``{path}`` is the path 
-the main Powerline project directory:
+to the main Powerline project directory:
 
 .. code-block:: vim
 
    source {path}/powerline/bindings/vim/plugin/source_plugin.vim
 
 Vundle installation
-*******************
+^^^^^^^^^^^^^^^^^^^
 
-If you're using Vundle you can add the following line to your ``vimrc``:
+If you're using Vundle you can add the following line to your :file:`vimrc`:
 
 .. code-block:: vim
 
    Bundle 'Lokaltog/powerline', {'rtp': 'powerline/bindings/vim/'}
 
 Shell prompts
-^^^^^^^^^^^^^
+-------------
 
 Bash prompt
-***********
+^^^^^^^^^^^
 
-Add the following line to your ``.bashrc``, where ``{path}`` is the absolute 
+Add the following line to your :file:`bashrc`, where ``{path}`` is the 
-path to your Powerline installation directory:
+absolute path to your Powerline installation directory:
 
 .. code-block:: bash
 
    . {path}/powerline/bindings/bash/powerline.sh
 
 Zsh prompt
-**********
+^^^^^^^^^^
 
-Add the following line to your ``.zshrc``, where ``{path}`` is the absolute 
+Add the following line to your :file:`zshrc`, where ``{path}`` is the 
-path to your Powerline installation directory:
+absolute path to your Powerline installation directory:
 
 .. code-block:: bash
 
@@ -171,7 +172,7 @@ path to your Powerline installation directory:
 Tmux statusline
 ^^^^^^^^^^^^^^^
 
-Add the following line to your ``.tmux.conf``, where ``{path}`` is the 
+Add the following line to your :file:`tmux.conf`, where ``{path}`` is the 
 absolute path to your Powerline installation directory::
 
    source '{path}/powerline/bindings/tmux/powerline.conf'

docs/source/troubleshooting.rst

@@ -1,96 +1,133 @@
+:tocdepth: 2
+
+***************
 Troubleshooting
-===============
+***************
+
+.. contents::
+
+General issues
+==============
 
 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 (see :ref:`font-patching`).
 
-    Make sure that vim is compiled with the ``--with-features=big`` flag.
+Make sure that you've configured gvim or your terminal emulator to use 
+a patched font (see :ref:`font-patching`).
 
-    If you're using rxvt-unicode, make sure that it's compiled with the 
+Make sure that vim is compiled with the ``--with-features=big`` flag.
-    ``--enable-unicode3`` flag.
 
-    If you're using iTerm2, please update to `this revision 
+If you're using rxvt-unicode, make sure that it's compiled with the 
-    <https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_ 
+``--enable-unicode3`` flag.
-    or newer.
 
-    You need to set your ``LANG`` and ``LC_*`` environment variables to 
+If you're using iTerm2, please update to `this revision 
-    a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's 
+<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_ 
-    documentation for information about setting these variables correctly.
+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 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).
+
+Make sure that you have patched all variants of your font (i.e. both the 
+regular and the bold font files).
 
 I'm unable to patch my font, what should I do?
-    Font patching is only known to work on most Linux and OS X machines. If 
+----------------------------------------------
-    you have followed the instructions on :ref:`font-patching` and still 
-    have problems, please submit an issue on GitHub.
 
-    You could also check out the `powerline-fonts 
+Font patching is only known to work on most Linux and OS X machines. If you 
-    <https://github.com/Lokaltog/powerline-fonts>`_ repository on GitHub for 
+have followed the instructions on :ref:`font-patching` and still have 
-    patched versions of some popular programming fonts.
+problems, please submit an issue on GitHub.
 
-The colors are weird in the default OS X Terminal app!
+You could also check out the `powerline-fonts 
-    The default OS X Terminal app is known to have some issues with the 
+<https://github.com/Lokaltog/powerline-fonts>`_ repository on GitHub for 
-    Powerline colors. Please use another terminal emulator. iTerm2 should 
+patched versions of some popular programming fonts.
-    work fine.
 
-    The arrows may have the wrong colors if you have changed the "minimum 
+The colors look weird in the default OS X Terminal app!
-    contrast" slider in the color tab of  your OS X settings.
+-------------------------------------------------------
 
-The colors are weird in iTerm2!
+The default OS X Terminal app is known to have some issues with the 
-    Please disable background transparency to resolve this issue.
+Powerline colors. Please use another terminal emulator. iTerm2 should work 
+fine.
+
+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 colors look weird in iTerm2!
+--------------------------------
+
+Please disable background transparency to resolve this issue.
 
 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"
+You need to tell tmux that it has 256-color capabilities. Add this to your 
+:file:`.tmux.conf` to solve this issue::
 
-    If you use iTerm2, make sure that you have enabled the setting 'Set 
+    set -g default-terminal "screen-256color"
-    locale variables automatically' in Profiles > Terminal > Environment.
+
+If you use iTerm2, make sure that you have enabled the setting 
+:guilabel:`Set locale variables automatically` in :menuselection:`Profiles 
+--> Terminal --> Environment`.
 
 I'm using PuTTY and I get huge gaps around the arrow glyphs!
-    Please uncheck :guilabel:`Treat CJK ambiguous characters as wide` in 
+------------------------------------------------------------
-    :menuselection:`Window --> Translation`.
+
+Please uncheck :guilabel:`Treat CJK ambiguous characters as wide` in 
+:menuselection:`Window --> Translation`.
 
 Vim-specific issues
--------------------
+===================
 
 The statusline has strange characters like ``^B`` in it!
-    Please add ``set encoding=utf-8`` to your :file:`vimrc`.
+--------------------------------------------------------
+
+Please add ``set encoding=utf-8`` to your :file:`vimrc`.
 
 The 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::
 
-        set fillchars+=stl:\ ,stlnc:\ 
+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:\ 
 
 The statusline is hidden/only appears in split windows!
-    Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
+-------------------------------------------------------
+
+Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
 
 I'm using gVim for Windows, and ``cmd`` windows keep popping up when working in git repos!
-    Either install ``libgit2`` and ``pygit2``, or disable the VCS segment in 
+------------------------------------------------------------------------------------------
-    your user configuration to resolve this issue.
+
+Either install ``libgit2`` and ``pygit2``, or disable the VCS segment in 
+your user configuration to resolve this issue.
 
 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
+Please install MacVim using this command::
 
-    Then install Powerline locally with ``pip install --user``, or by 
+    brew install macvim --env-std --override-system-vim
-    running these commands in the ``powerline`` directory::
 
-        ./setup.py build
+Then install Powerline locally with ``pip install --user``, or by 
-        ./setup.py install --user
+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
+This is caused by an invalid ``sys.path`` when using system vim and system 
+Python. Please try to select another Python distribution::
 
-    See the `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ 
+    sudo port select python python27-apple
-    for a discussion and other possible solutions for this issue.
+
+See the `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ 
+for a discussion and other possible solutions for this issue.