startproject_ext
-----------------

This is a simple Django-admin command to automate some of the project initiation activitiy 
such as creating clean directory structure, settings overrides, etc. This is based on 
django-admin startproject command.

Currently, this command generates extended directory structure, initializes support for multiple 
settings, and support for project-specific 3rdparty libraries. If you have worked with rails 
before, you might be familiar with this approach. Yes, the idea is heavily borrowed from there.

For more info on Django-admin commands see:
- Writing custom django admin command. 
  http://docs.djangoproject.com/en/1.2/howto/custom-management-commands/

Contents
1. Extended directory structure
2. Multiple settings
3. Project-spesific 3rd party library
4. Installation
5. TODO


1. Extended directory structure

Instead of generating the usual, this command genereates the  following directory 
structure:

<project_name>
|-- config/
|   |-- __init__.py
|   |-- settings/
|   |   |-- default.py
|   |   |-- development.py
|   |   |-- __init__.py
|   |   |-- production.py
|   |   |-- test.py
|   `-- wsgi/
|-- db/
|-- __init__.py
|-- lib/
|-- manage.py
|-- settings.py
`-- urls.py

The new directory structure provides cleaner layout by providing compartments for database 
files (sqlite), 3rd party libraries, wsgi config, and settings overrides


2. Multiple settings

By using startproject_ext instead of the usual startproject, your generated settings.py will 
be modified to support multiple setting overrides.

Setting overrides are python modules that overrides variables defined in main settings.py and
placed under config/settings directory.

This new approach requires that main settings.py is not to be edited directly. Instead, 
you can edit the default overrides in config/settings/default.py. Or one of the recomended
modules provided there. You can even provide your own.

Which overrides will eventually be loaded is be determined by the value of <PROJECTNAME>_ENV 
environment variable or from the command line (see TODO). 

Here's an example of how to select setting overrides during runtime

|# django-admin startproject candi
|# cd candi
(work on project, startapp, etc...)
|# export CANDI_ENV = test
|# ./manage.py sycndb
|# ./manage.py test

3. 3rd party library

This is simple. Your main setting.py now adds lib to PYTHONPATH. So you can place any
project spesific 3rd party libraries there and have them added to PYTHONPATH automatically

Do remember though, if your lib is another django app (with models, views, etc) don't forget
to add it to INSTALLED_APPS in your settings override. 

4. Installation

git clone the repo and add startproject_ext to PYTHONPATH

# cd ~
# git clone git@github.com:bluearth/startproject_ext.git
# export PYTHONPATH=/home/bluearth/startproject_ext:$PYTHONPATH


5. TODO

* Provide painless and platform independent setup. Perhaps using python egg?
* Overrides should append/update to list, tuple, dict values instead of replacing them.
* Choose setting override via command line parameter