Source

django-in-a-box / docs / wiki / layout / project-directories.md

Full commit

Project Directories

Django-in-a-Box’s default project layout looks like this:

project_dir/
|-- apps/
|-- etc/ -> etcs/deployment
|-- etc.templates/
|   |-- common.py
|   |-- fastcgi.light.conf
|   |-- fastcgi.svd.conf
|   |-- lighttpd.conf
|   |-- lighttpd.svd.conf
|   |-- mimetypes.light.conf
|   `-- supervisord.conf
|-- etcs/
|   `-- deployment/
|       |-- fastcgi.light.conf
|       |-- fastcgi.svd.conf
|       |-- lighttpd.conf
|       |-- lighttpd.svd.conf
|       |-- mimetypes.light.conf
|       `-- supervisord.conf
|-- libs/
|   |-- djpave.py
|   `-- templatecfg.py
|-- media/
|   |-- css/
|   |-- img/
|   |-- js/
|   `-- favicon.ico
|-- settings/
|   |-- common.py
|   |-- development.py
|   |-- production.py
|   `-- staging.py
|-- static/
|   `-- error/
|       |-- 404.html
|       |-- 500.html
|       `-- 503.html
|-- templates/
|-- README
|-- __init__.py
|-- pavement.py
`-- urls.py

The project directory is for all the content which remains invariant (read-only) while your site is running. It is the top-level of the version control repository, as it contains everything needed to install and run a copy of the site: media, code, templates and settings. It also contains documentation and requirement specifications, since these also need to be tracked by the VCS.

apps/
Contains modules representing all the site-specific Django apps for this project. There is no need for an __init__.py file because it is added to the Python module search path automatically. This allows apps to be imported directly by their name, instead of project.apps.app_name.
libs/
Contains modules which are not Django apps but still need to be imported in your code. Again, this is automatically added to the search path. This already houses a couple of libraries which are used by the pavement file.
etc/, etc.templates/ and etcs/
Contains all of the project's plaintext configuration files; out of the box this is just Supervisor and lighttpd, but you can add to this. etc.templates/ holds Jinja2 templates for the various configuration files, etcs/ holds multiple directories (each corresponding to a different deployment) with the rendered plaintext configurations, and etc/ is a symlink to a single etcs/deployment directory.
media/
Holds all site media: JavaScript, CSS and images. These do not change based on the installation, and need to be tracked by the VCS, so are kept in the project directory.
settings/
Holds all of the various deployment-specific settings files, along with the common.py settings module.
static/
A directory for the various non-media static files required by your project. For example, static error pages for your web server (as opposed 404 templates for your app), and other pieces of raw data which your app might need that won't be served directly out of the media/ directory.
templates/
Should contain all of your site-wide Django/Jinja2 templates. You should also have templates/ subdirectories in some of your applications.
pavement.py
A file containing definitions for Paver. Paver is a tool for managing software projects, much like Fabric, Make, Rake or Capistrano. This replaces the traditional manage.py within Django-in-a-Box; instead of running python manage.py command, use paver manage command.