Project Layout Philosophy

For ease of use, Artshow Jockey has been supplied as a nearly-ready-to-run Django project, including both application/component and project/site directories, and settings that require very little customisation. This, I believe, does not prevent an experienced Django developer from using the components in the traditional way, or including them into another project/site.

In my development experience, I am frequently creating copies of the same project:

• One or two copies for my desktop, multiplied by the number of collaborators
• One or two copies for demonstration or testing
• One copy for production

If I was only distributing apps, I'd need to do a "startproject" on each of these and put together settings files from scratch, each time. This is wasteful, especially since there are very few changes in settings.py between each of the above. Ie, I also want to distribute the "project" directory, too, but in a way that allows most of settings.py to be checked-in to our SCM, and have the user just provide differences.

The Solution

• The "project" directory is checked in (either separately, or as one bug chunk along with all the apps).
• settings.py is renamed to common_settings.py
• manage.py and wsgi.py (and anything else using DJANGO_SETTINGS_MODULE) are changed to use local_settings. Note no leading module name.
• A local_settings.py.example is provided as a template. This file has from projectname.common_settings import * at the top. The administrator copies this file to local_settings.py and makes edits.
• common_settings.py and local_settings.py.example are checked-in to the SCM, and local_settings.py is marked to be ignored.

So now, Django will load all settings that are common, regardless of where the project is run from, and any differences are overridden with the local settings. settings.py is removed completely, to ensure that code importing the module directly fails: it should be using from django.conf import settings instead.

Alternatives

If your project works better by having separate check-ins for each component/app, you can make the following adjustments

• Ensure the project directory itself is also checked in.
• Put local_settings.py.example into the project directory.
• Put manage.py, with the default settings module change, into the project directory as well.

Installation instructions become the following:

• Don't run "startproject". Instead create an empty directory and check-out all the apps and the project file into this directory
• Copy local_settings.py.example from the project directory into the top level directory, calling it local_settings.py and editing changes
• Copy manage.py into the top level directory, with no edits. Copying here is important as python adds the directory containing main into the Python search path, which is critical for Django to function. A hard link would work, too, but a symbolic link will not.