link example cfg, fix markup errors and show content table, closes #52

and also reword a few paragraphs as suggested via mail.

docs/docs/configuration/server.rst

@@ -2,7 +2,9 @@ Server Configuration
 ====================
 
 The Isso configuration file is an `INI-style`__ textfile. It reads integers,
-booleans and strings.  Below is a basic example:
+booleans, strings and lists. Here's the default isso configuration:
+:download:`isso.example.cfg </isso.example.cfg>`. A basic configuration from
+scratch looks like this:
 
 .. code-block:: ini
 

docs/docs/index.rst

@@ -5,6 +5,15 @@ Welcome to the Isso's documentation. This documentation will help you get
 started fast. If you get any problems when using Isso, you can find the answer
 in troubleshooting or you can ask me on IRC or GitHub.
 
+Documentation overview:
+
+.. toctree::
+   :maxdepth: 1
+
+   install
+   quickstart
+   troubleshooting
+
 What's Isso?
 ------------
 

docs/docs/install.rst

@@ -6,15 +6,20 @@ Requirements:
 -  Python 2.6, 2.7 or 3.3
 -  a working C compiler
 
-Install Isso with PIP_:
+Install Isso with `pip <http://www.pip-installer.org/en/latest/>`_:
 
 .. code-block:: sh
 
     ~> pip install isso
 
-.. _PIP: http://www.pip-installer.org/en/latest/
+`Dont't have pip <https://twitter.com/gardaud/status/357638468572151808>`_?
 
-Init scripts:
+.. code-block:: sh
+
+    ~> easy_install isso  # cross your fingers
+
+Init scripts to run Isso as a service (check your distribution's documentation
+for your init-system; e.g. Debian uses SysVinit, Fedora uses SystemD):
 
 -  SystemD: https://github.com/jgraichen/debian-isso/blob/master/debian/isso.service
 -  SysVinit: https://github.com/jgraichen/debian-isso/blob/master/debian/isso.init

docs/docs/quickstart.rst

@@ -2,20 +2,25 @@ Quickstart
 ==========
 
 Assuming you have successfully :doc:`installed <install>` Isso, here's
-a quickstart quide that covers common setups.
+a quickstart quide that covers common setups. Sections covered:
+
+.. contents::
+    :local:
+    :depth: 1
 
 
 Configuration
 -------------
 
 You must provide a custom configuration. Most default parameters are useful for
-development, not persistence. Two most important options are `dbpath` to set
+development, not persistence. The two most important options are `dbpath` to
-the location of your database and `host` which is your website:
+set the location of your database and your website's name `host` where you want
+to comment on:
 
 .. code-block:: ini
 
     [general]
-    ; database location, check permissions
+    ; database location, check permissions, created if not exists
     dbpath = /var/lib/isso/comments.db
     ; your website or blog (not the location of Isso!)
     host = http://example.tld/
@@ -51,6 +56,8 @@ URLs for activation and deletion:
     [smtp]
     ; SMTP settings
 
+For more details, see :doc:`server <configuration/server>` and
+:doc:`client <configuration/client>` configuration.
 
 Migration
 ---------
@@ -107,6 +114,9 @@ configuration looks like this:
         }
     }
 
+Integration
+-----------
+
 Now, you embed Isso to your website:
 
 .. code-block:: html
@@ -129,13 +139,13 @@ a comment to see if the setup works. If not, see :doc:`troubleshooting`.
 Deployment
 ----------
 
-Isso ships with a built-in web server, which is useful for the initial setup.
+Isso ships with a built-in web server, which is useful for the initial setup
-But it is not recommended to use the built-in web server for production. A few
+and may be used in production for low-traffic sites (up to 20 requests per
-WSGI servers are supported out-of-the-box:
+second). It is recommended to use a "real" WSGI server to run Isso, e.g:
 
-  * gevent_, coroutine-based network library
+* gevent_, coroutine-based network library
-  * uWSGI_, full-featured uWSGI server
+* uWSGI_, full-featured uWSGI server
-  * gunicorn_, Python WSGI HTTP Server for UNIX
+* gunicorn_, Python WSGI HTTP Server for UNIX
 
 .. _gevent: http://www.gevent.org/
 .. _uWSGI: http://uwsgi-docs.readthedocs.org/en/latest/