Change hacking howto to use a virtualenv.

docs/hacking_howto.rst

@@ -12,10 +12,10 @@ Summary
 =======
 
 This chapter helps you get a minimal installation of Kitsune up and
-running so as to make it easier for contributing.
+running to make it easier to contribute.
 
-If you're setting Kitsune up for deployment, make sure you read all
-the way to the end and then read the additional sections.
+If you're setting Kitsune up for deployment, instead of development, make
+sure you read all the way to the end and then read the additional sections.
 
 If you have any problems getting Kitsune running, let us know. See the
 :ref:`contact-us-chapter`.
@@ -46,10 +46,9 @@ so if you run into problems, let us know.
 Linux
 -----
 
-We know these work in Debian Testing (Wheezy) and Ubuntu 12.04 and
-will probably work in other distributions. It's likely that you'll
-encounter some steps that are slightly different. If you run into
-problems, let us know.
+We know these work in Debian, Ubuntu, Arch, and will probably work in other
+distributions. It's likely that you'll encounter some steps that are
+slightly different. If you run into problems, let us know.
 
 
 Requirements
@@ -60,13 +59,13 @@ These are required for the minimum installation:
 * git
 * Python 2.6 or 2.7
 * pip: `<http://www.pip-installer.org/en/latest/>`_
+* virtualenv
 * MariaDB 5.5 server and client headers
 * Memcached Server
 * libxml and headers
 * libxslt and headers
 * libjpeg and headers
 * zlib and headers
-* LESS 1.4.1
 
 These are optional:
 
@@ -112,23 +111,12 @@ memcached you can start it and configure it to run on startup using::
    Assuming you have memcache configured to listen to 11211.
 
 
-LESS
-----
-
-To install LESS you will first need to `install Node.js and NPM
-<https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager>`_.
-
-Now install LESS using::
-
-    $ npm install -g less@1.4.1
-
-
 Getting the Source
 ==================
 
 Grab the source from Github using::
 
-    $ git clone --recursive git://github.com/mozilla/kitsune.git
+    $ git clone --recursive https://github.com/mozilla/kitsune.git
     $ cd kitsune
 
 
@@ -140,6 +128,26 @@ Grab the source from Github using::
        $ git submodule update --init --recursive
 
 
+Setting up an Environment
+=========================
+
+It is strongly recommended to run Kitsune in a virtual environment, which is a
+tool to isolate Python environments from eachother and the system. It makes
+local development much easier, especially when working on multiple projects.
+
+To create a virtual environment::
+
+    $ virtualenv venv
+
+which creates a virtualenv named "venv" in your current directory (which should
+be the root of the git repo. Now activate the virtualenv::
+
+    $ source venv/bin/activate
+
+You'll need to run this command every time you work on Kitsune, in every
+terminal window you use.
+
+
 Installing dependencies
 =======================
 
@@ -149,13 +157,11 @@ Compiled Packages
 There are a small number of compiled packages, including the MySQL
 Python client.
 
-You can install these either with your system's package manager or
-with ``pip``.
-
-To use pip, do this::
-
-    $ sudo pip install -r requirements/compiled.txt
+For development, you should install these with ``pip``, but for
+other situations you may want to use your system package manager.
 
+::
+    $ pip install -r requirements/compiled.txt
 
 If you want to use your system's package manager, you'll need to go
 through ``requirements/compiled.txt`` and install the dependencies by
@@ -170,9 +176,25 @@ directory, also known as the "vendor library". This makes the packages
 available to Python without installing them globally and keeps them
 pinned to known-compatible versions.
 
+If you do not have a vendor library, see the section about getting the source
+above.
+
 See the :ref:`vendor library <vendor-chapter>` documentation for more
 information on getting the vendor lib and keeping it up to date.
 
+Javascript Packages
+-------------------
+
+Kitsune relies on a small number of Javascript packages. To get those, you will
+need to `install Node.JS and NPM
+<https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager>`_.
+
+Now install the javascript dependencies with::
+
+    $ npm install
+
+This should create a directory named ``node_modules`` in your git repo.
+
 
 Configuration and Setup
 =======================
@@ -338,6 +360,7 @@ Running the test suite is easy::
 
     $ ./manage.py test -s --noinput --logging-clear-handlers
 
+This may open a Firefox window, which will close automatically.
 
 For more information, see the :ref:`test documentation
 <tests-chapter>`.