add install docs

docs/index.rst

@@ -19,9 +19,15 @@ Contents
 .. toctree::
    :maxdepth: 1
 
+   install
    l10n
    php
-   
+
+
+Installation
+------------
+
+Need to install bedrock? :ref:`Read this<install>` for instructions.
 
 Localization
 ------------
@@ -29,44 +35,6 @@ Localization
 Looking for help on how l10n works on bedrock? :ref:`Look here <l10n>`
 for more details.
 
-Installation
-------------
-
-It's a simple `Playdoh
-<http://playdoh.readthedocs.org/en/latest/index.html>`_ instance, and
-works like django.::
-
-    git clone --recursive git://github.com/mozilla/bedrock.git
-    cd bedrock
-    cp settings/local.py-dist settings/local.py
-    ./manage.py runserver
-
-To install bedrock, fire a commandline and type the following::
-
-    $ virtualenv venv
-    $ source venv/bin/activate
-    $ pip install -r requirements/dev.txt
-
-Once you've done that, you'll need to configure the application to run
-locally. Copy the `local.py-dist` file to `settings/local.py` file::
-
-    $ cp settings/local.py-dist settings/local.py
-
-You will need to have a less compiler. You can get one on debian/ubuntu by
-installing the "libjs-less" package.
-
-Make it run
------------
-
-To make the server run, make sure you are inside a virtualenv, and then
-run the server with your local settings::
-
-    $ python manage.py runserver --settings settings.local
-
-If you are not inside a virtualenv, you can activate it by doing::
-
-    $ source venv/bin/activate
-
 PHP
 ---
 

docs/install.rst

@@ -0,0 +1,66 @@
+.. _install:
+
+==================
+Installing Bedrock
+==================
+
+Installation
+------------
+
+It's a simple `Playdoh
+<http://playdoh.readthedocs.org/en/latest/index.html>`_ instance, which is a Django project.
+
+These instructions assume you have `git` and `pip` installed. If you don't have `pip` install, you can install it with `easy_install pip`.
+
+Start by getting the source::
+
+    $ git clone --recursive git://github.com/mozilla/bedrock.git
+    $ cd bedrock
+
+You need to create a virtual environment for Python libraries. Skip the first instruction if you already have virtualenv installed::
+
+    $ pip install virtualenv                     # installs virtualenv, skip if already have it
+    $ virtualenv venv                            # create a virtual env in the folder `venv`
+    $ source venv/bin/activate                   # activate the virtual env
+    $ pip install -r requirements/compiled.txt   # installs compiled dependencies
+
+If you are on OSX and some of the compiled dependencies fails to compile, try explicitly setting the arch flags and try again::
+
+    $ export ARCHFLAGS="-arch i386 -arch x86_64"
+    $ pip install -r requirements/compiled.txt
+
+Now configure the application to run locally by creating your local settings file::
+
+    $ cp settings/local.py-dist settings/local.py
+
+You shouldn't need customize anything in there yet.
+
+Lastly, you need to install `node` and the `less` package. Soon you won't need this for local development but currently it compiles the LESS CSS code on the server-side::
+
+    $ npm -g install less
+
+You don't have to use npm to install less; feel free to install it however you want.
+
+Add the path to the LESS compiler in you `local.py` config file in the `settings` folder. It is most likely `/usr/local/bin/lessc`, so add the following line::
+
+    LESS_BIN = '/usr/local/bin/lessc'
+
+Make it run
+-----------
+
+To make the server run, make sure you are inside a virtualenv, and then
+run the server::
+
+    $ ./manage.py runserver
+
+If you are not inside a virtualenv, you can activate it by doing::
+
+    $ source venv/bin/activate
+
+Notes
+-----
+
+A shortcut for activating virtual envs in zsh is `. venv/bin/activate`. The dot is the same as `source`.
+
+There's a project called `virtualenvwrapper <http://www.doughellmann.com/docs/virtualenvwrapper/>`_ that provides a better interface for managing/activating virtual envs, so you can use that if you want.
+