Streamline installation doc, now using pip (#252)

* Fix conf files to reflect module renaming

Python module was renamed budget → ihatemoney (see #243 and 6923367).
Now, "budget" relates to nothing.

* Harmonize `APPLICATION_ROOT` doc with other settings

* Fix link markup

* Switch documentation to recomend pip over git

- Update installation instruction
- Clearly separate dev setup from installation
- Some rewordings/section-ization by the way

* Add a hint on how to find the static path

This is a downside on the pip choice over git for installation.

We will have to ease that a bit. By doc or by code, before next release.

* Make the nginx deployment doc more accurate

* Add a big fat warning about SECRET_KEY in doc

2 files changed, 92 insertions, 29 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index b0a829f..d2bdbcc 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -4,6 +4,52 @@ Contributing
 Setup a dev environment
 =======================
 
+You must develop on top of the git master branch::
+
+  git clone https://github.com/spiral-project/ihatemoney.git
+
+Then you need to build your dev environments. Choose your way…
+
+The quick way
+-------------
+
+If System :ref:`installation-requirements` are fulfilled, you can just issue::
+
+    make serve
+
+It will setup a `virtualenv <https://pypi.python.org/pypi/virtualenv>`_,
+install dependencies, and run the test server.
+
+The hard way
+------------
+
+Alternatively, you can also use the `requirements.txt` file to install the
+dependencies yourself. That would be::
+
+     pip install -r requirements.txt
+
+And then run the application::
+
+    cd ihatemoney
+    python run.py
+
+Accessing dev server
+--------------------
+
+In any case, you can point your browser at `http://localhost:5000 <http://localhost:5000>`_.
+It's as simple as that!
+
+
+Updating
+--------
+
+In case you want to update to newer versions (from git), you can just run the "update" command::
+
+  make update
+
+Useful settings
+----------------
+
 It is better to actually turn the debugging mode on when you're developing.
 You can create a ``settings.cfg`` file, with the following content::
 
@@ -47,7 +93,7 @@ End-user
 --------
 
 You are using the application and found a bug? You have some ideas about how to
-improve the project? Please tell us [by filling a new issue](https://github.com/spiral-project/ihatemoney/issues).
+improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_.
 Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I will
 update the issue tracker with your feedback.
 
diff --git a/docs/installation.rst b/docs/installation.rst
index ade647f..e0f70df 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,10 +1,7 @@
 Installation
 ############
 
-First, you need to get the source files. One way to get them is to download
-them from the github repository, using git::
-
-  git clone https://github.com/spiral-project/ihatemoney.git
+.. _installation-requirements:
 
 Requirements
 ============
@@ -13,31 +10,45 @@ Requirements
 
 * **Python**: either 2.7, 3.4, 3.5, 3.6 will work.
 * **A Backend**: to choose among MySQL, PostgreSQL, SQLite or Memory.
+* **Virtualenv** (recommended): `virtualenv` package under Debian/Ubuntu.
+
+We recommend to use `virtualenv <https://pypi.python.org/pypi/virtualenv>`_ but
+it will work without if you prefer.
+
+If wondering about the backend, SQLite is the simplest and will work fine for
+most small to medium setups.
+
+Prepare virtualenv (recommended)
+================================
+
+Choose an installation path, here `/home/john/ihatemoney`.
+
+Create a virtualenv::
+
+    virtualenv  -p /usr/bin/python3 /home/john/ihatemoney
 
-We recommend to use `pip <https://pypi.python.org/pypi/pip/>`_ and
-`virtualenv <https://pypi.python.org/pypi/virtualenv>`_ but it will work
-without if you prefer.
+Activate the virtualenv::
 
-If you have everything installed, you can just issue::
+    source /home/john/ihatemoney/bin/activate
 
-    make serve
+.. note:: You will have to re-issue that ``source`` command if you open a new
+          terminal.
 
-Alternatively, you can also use the `requirements.txt` file to install the
-dependencies yourself (that's what the `make serve` does). That would be::
+Install
+=======
 
-     pip install -r requirements.txt
+Install the latest release with pip::
 
-And then run the application::
+  pip install ihatemoney
 
-    cd ihatemoney
-    python run.py
+Test it
+=======
 
-In any case, you can point your browser at `http://localhost:5000 <http://localhost:5000>`_.
-It's as simple as that!
+Once installed, you can start a test server::
 
-In case you want to update to newer versions, you can just run the "update" command::
+  ihatemoney runserver
 
-  make update
+And point your browser at `http://localhost:5000 <http://localhost:5000>`_.
 
 Deploy it
 =========
@@ -59,12 +70,19 @@ With Apache and mod_wsgi
 With Nginx, Gunicorn and Supervisord
 ------------------------------------
 
-1. Add the lines in conf/supervisord.conf to your supervisord.conf file.
-2. Copy and paste the content of conf/nginx.conf in your nginx conf file.
-3. reload both nginx and supervisord. It should be working ;)
+.. note:: For the 3 configuration files mentioned below, you will need to fix
+          the paths to reflect yours.
+
+1. Copy *conf/gunicorn.conf.py* to */etc/ihatemoney/gunicorn.conf.py*
+2. Copy *conf/supervisord.conf* to */etc/supervisor/conf.d/ihatemoney.conf*
+3. Copy *conf/nginx.conf* with your nginx vhosts [#nginx-vhosts]_
+4. Reload both nginx and supervisord. It should be working ;)
 
 Don't forget to set the right permission for your files !
 
+.. [#nginx-vhosts] typically, */etc/nginx/conf.d/* or
+   */etc/nginx/sites-available*, depending on your distribution.
+
 Configuration
 =============
 
@@ -72,6 +90,8 @@ ihatemoney relies on a configuration file. If you run the application for the
 first time, you will need to take a few moments to configure the application
 properly.
 
+.. warning:: You **must** customize the ``SECRET_KEY`` on a production installation.
+
 +----------------------------+---------------------------+----------------------------------------------------------------------------------------+
 | Setting name               |  Default                  | What does it do?                                                                       |
 +============================+===========================+========================================================================================+
@@ -90,6 +110,9 @@ properly.
 | ADMIN_PASSWORD             |                           | To generate the proper password HASH, use ``ihatemoney generate_password_hash``        |
 |                            |                           | and copy its output into the value of *ADMIN_PASSWORD*.                                |
 +----------------------------+---------------------------+----------------------------------------------------------------------------------------+
+| APPLICATION_ROOT           |  ``""``                   | If empty, ihatemoney will be served at domain root (e.g: *http://domain.tld*), if set  |
+|                            |                           | to ``"foo"``, it will be served from a "folder" (e.g: *http://domain.tld/foo*)         |
++----------------------------+---------------------------+----------------------------------------------------------------------------------------+
 
 In a production environment
 ---------------------------
@@ -105,9 +128,3 @@ the IHATEMONEY_SETTINGS_FILE_PATH environment variable.
 e.g.::
 
     $ export IHATEMONEY_SETTINGS_FILE_PATH="/path/to/your/conf/file.cfg"
-
-Note that you can also pass additional flask parameters with this file.
-e.g. If you want to prefix your URLs to serve ihatemonney in the *folder*
-of a domain, use the following: ::
-
-    APPLICATION_ROOT='/budget'