Updated the documentation on installing oscar for contributors

docs/source/contributing.rst

@@ -1,12 +1,9 @@
 Contributing
 ============
 
-Make sure you've read http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
-
 * New features should be discussed on the mailing list (or in the meetings) before serious work starts
 * Pull requests will be rejected if sufficient tests aren't provided
-* Please updated the documentation when altering behaviour or introducing new features 
-
+* Please update the documentation when altering behaviour or introducing new features 
 
 Contents:
 

docs/source/contributing/conventions.rst

@@ -2,6 +2,8 @@
 Conventions
 ===========
 
+Make sure you've read http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
+
 Coding conventions
 ------------------
 

docs/source/contributing/installation.rst

@@ -1,51 +1,78 @@
+=======================================
 Installing django-oscar for development
 =======================================
 
-Set up `virtualenv` if you haven't already done so::
+Note that these instructions assume you are developing on Ubuntu.
+
+Virtual environment
+-------------------
+
+Set up ``pip`` and ``virtualenv`` if you haven't already done so::
 
     sudo apt-get install python-setuptools
     sudo easy_install pip
     sudo pip install virtualenv virtualenvwrapper
-    echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc
+    echo "source `which virtualenvwrapper`" >> ~/.bashrc
 
-Note: Fedora (and possibly other Red Hat based distros) installs virtualenvwrapper.sh in /usr/bin path, so the last line above should read::
+Reload bash to add the virtualenvwrapper commands to your path::
 
-    echo "source /usr/bin/virtualenvwrapper.sh" >> ~/.bashrc
+    . ~/.bashrc
 
-Reload bash with the following command::
+Create a virtualenv for developement::
 
-    ~/.bashrc
-
-Do the following from your workspace folder::
-
-    mkdir oscar
-    cd oscar
     mkvirtualenv --no-site-packages oscar
     workon oscar
+
+Forking django-oscar
+--------------------
+
+Sign in to github, navigate to https://github.com/tangentlabs/django-oscar and click "Fork".  This will create a 
+copy of the repository in your account.
+
+Now clone the remote repository to your machine::
+
+    cd workspace
+    git clone git@github.com:username/django-oscar.git
     
-After checking out your fork, install the latest version of Django into your virtualenv (currenty a beta of 1.3)::
+See the github guide to forking for more details (http://help.github.com/fork-a-repo/).      
 
-    pip install django
+Install django-oscar and dependencies
+-------------------------------------
 
-Install all packages from the requirements file (optional)::
+Install django and the packages from the requirements file, which aren't essential but are useful
+for testing and development::
 
+    pip install django
     pip install -r requirements-dev.txt
 
-This just provides some useful tooling for developing a django project - the installed
-modules are not mandatory to run oscar.
-
-Install oscar in development mode within your virtual env::
+Install oscar in development mode within your virtualenv::
 
+    cd django-oscar
     python setup.py develop
 
 Note: In case of gcc crashing and complaining in-between installation process,
 make sure you have appropriate -devel packages installed (ie. mysql-devel) in
 your system.
 
-Now create a `local_settings.py` file which contains details of your local database
-that you want to use for development.  Be sure to create two databases: one for development
-and one for running the unit tests (prefix `test_` on the normal db name).
+Now create a ``settings_local.py`` file which contains details of your local database
+that you want to use for development.  At a minimum, this needs to define the ``DATABASES`` tuple.
+
+Developing
+----------
+
+Developing oscar normally involves working on a django project which uses oscar
+as a installed app.  There are several such projects within the ``examples`` folder:
+
+* The ``vanilla`` project does not customise oscar at all and uses everything in its 
+  default format.  It represents a blank canvas for an ecommerce shop.
+* The ``demo`` project does customise oscar, and is intended to demonstrate the range 
+  of features in oscar.   
+
+Each example shop has its own ``manage.py`` executable which you can use to create 
+your database::
 
+    ./manage.py syncdb
+ 
 Install sample data
 -------------------
 
@@ -55,30 +82,20 @@ following commands::
     cd examples/vanilla
     ./manage.py import_catalogue ../sample-data/books.csv
     ./manage.py import_images ../sample-data/book-images/
-    ./manage.py update_index
-
-
-Developing
-----------
-
-Developing oscar normally involves working on a django project which uses oscar
-as a installed app.  There are several such projects within the `examples` folder - the 
-`defaultshop` project does not customise oscar at all and uses everything in its 
-default format.
-
-Each example shop has its own `manage.py` executable which you can use to create 
-your database::
-
-    ./manage.py syncdb
+    ./manage.py update_index 
+ 
+ 
+Helper scripts
+-------------- 
     
 There is a shortcut script for dropping all of a projects's apps and rerunning `syncdb` in
 the `examples` folder - you need to specify which project to act on::
 
-    ./recreate_project_tables.sh defaultshop
+    ./recreate_project_tables.sh vanilla
     
 There is a similar script for running tests::
 
-    ./run_tests.sh defaultshop
+    ./run_tests.sh vanilla
     
 This specifies a sqlite3 database to use for testing and filters out the useless output.
 

docs/source/contributing/testing.rst

@@ -1,9 +1,10 @@
+=======
 Testing
 =======
 
 There is a similar script for running tests::
 
     cd examples
-    ./run_tests.sh defaultshop
+    ./run_tests.sh vanilla
     
 This specifies a sqlite3 database to use for testing and filters out the useless output.