From a3600158de61c6d257b04643eb76e543eb91f677 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kim=20Silkeb=C3=A6kken?= <kim.silkebaekken@gmail.com>
Date: Mon, 28 Jan 2013 13:55:45 +0100
Subject: [PATCH] Add a quick setup guide to the docs

---
 docs/source/configuration.rst | 82 ++++++++++++++++++++++++++++++-----
 1 file changed, 71 insertions(+), 11 deletions(-)

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 7efd19d6..29bf5d4c 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -2,6 +2,10 @@
 Configuration
 *************
 
+.. note:: **You DO NOT have to fork the main GitHub repo to personalize your 
+   Powerline configuration!** Please read through the :ref:`quick-guide` for 
+   a quick introduction to user configuration.
+
 Powerline is configured with one main configuration file, and with separate 
 configuration files for themes and colorschemes. All configuration files are 
 written in JSON, with the exception of segment definitions, which are 
@@ -12,7 +16,7 @@ Powerline provides default configurations in the following locations:
 `Main configuration`_
     :file:`powerline/config.json`
 `Colorschemes`_
-    :file:`powerline/colorschemes/default.json`
+    :file:`powerline/colorschemes/{extension}/default.json`
 `Themes`_
     :file:`powerline/themes/{extension}/default.json`
 
@@ -21,21 +25,77 @@ configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for
 Linux users, and in :file:`~/.config/powerline` for OS X users. This usually 
 corresponds to :file:`~/.config/powerline` on both platforms.
 
-The easiest way of creating your own version of any configuration file is to 
-copy the configuration file from the main package to the corresponding path 
-in your user-specific config directory and make your changes to the new 
-file. Example:
+.. _quick-guide:
+
+Quick setup guide
+=================
+
+This guide will help you with the initial configuration of Powerline.
+
+Start by copying the entire set of default configuration files to the 
+corresponding path in your user config directory:
 
 .. code-block:: sh
 
-    $ cp /path/to/powerline/colorschemes/default.json \
-        ~/.config/powerline/colorschemes/mycolorscheme.json
+   mkdir ~/.config/powerline
+   cp -R /path/to/powerline/config_files/* ~/.config/powerline
 
-    $ vim ~/.config/powerline/colorschemes/mycolorscheme.json
+Each extension (vim, tmux, etc.) has its own theme, and they are located in 
+:file:`{config directory}/themes/{extension}/default.json`.
 
-.. note:: If you're creating a custom colorscheme or theme, remember to 
-   rename it and update your main configuration to use the new 
-   colorscheme/theme!
+If you want to move, remove or customize any of the provided segments, you 
+can do that by updating the segment dictionary in the theme you want to 
+customize. A segment dictionary looks like this:
+
+.. code-block:: javascript
+
+   {
+       "name": "segment_name"
+       ...
+   }
+
+You can move the segment dictionaries around to change the segment 
+positions, or remove the entire dictionary to remove the segment from the 
+prompt or statusline.
+
+.. note:: It's essential that the contents of all your configuration files 
+   is valid JSON! It's strongly recommended that you run your configuration 
+   files through ``jsonlint`` after changing them.
+
+Some segments need a user configuration to work properly. Here's a couple of 
+segments that you may want to customize right away:
+
+**E-mail alert segment**
+    You have to set your username and password (and possibly server/port) 
+    for the e-mail alert segment. If you're using GMail it's recommended 
+    that you `generate an application-specific password 
+    <https://accounts.google.com/IssuedAuthSubTokens>`_ for this purpose.
+
+    Open a theme file, scroll down to the ``email_imap_alert`` segment and 
+    set your ``username`` and ``password``.  The server defaults to GMail's 
+    IMAP server, but you can set the server/port by adding a ``server`` and 
+    a ``port`` argument.
+**Weather segment**
+    The weather segment will try to find your location using a GeoIP lookup, 
+    so unless you're on a VPN you probably won't have to change the location 
+    query.
+   
+    If you want to change the location query or the temperature unit you'll 
+    have to update the segment arguments. Open a theme file, scroll down to 
+    the weather segment and update it to include unit/location query 
+    arguments:
+
+    .. code-block:: javascript
+
+       {
+           "name": "weather",
+           "priority": 50,
+           "divider_highlight_group": "background:divider"
+           "args": {
+               "unit": "f",
+               "location_query": "oslo, norway"
+           }
+       },
 
 Main configuration
 ==================