.. contents::

This recipe allows you to setup a Django_ project through `zc.buildout`_.

Usage
*****

The main scope of the recipe is to abstract out the ``settings.py`` file,
allowing settings to reside inside the buildout instead of having them reside
into code (leading to an awkard handling of the same in respect to versioning,
for example). The ``settings.py`` file is generated by a template, either the
default one, the default one and a user extension, or a totally new one.

The template uses the Tempita_ templating system.

The most basic usage of this recipe is as follows: ::

    [buildout]
    parts = django

    [django]
    recipe = djc.recipe
    project = my.project

Where ``my.project`` is an importable package containing a ``urls`` module and
a ``templates`` directory.

As you see, very few options are specified here: the defaults are used to build
up the ``settings.py`` file.

Of course, real examples tend to be slightly more complex: for example here is
a buildout used for Satchmo_: ::

    [buildout]
    parts =
        omelette
    
    find-links =
        http://dist.plone.org/thirdparty/
    
    versions = versions
    
    eggs =
        PIL
        pysqlite
        Django
        pycrypto
        PyYAML
        django-registration
        django-livesettings
        django-keyedcache
        django-signals-ahoy
        django-caching-app-plugins
        django-threaded-multihost
        sorl-thumbnail
        trml2pdf
        ReportLab
        Satchmo
        example.site
    
    [django]
    recipe = djc.recipe.django
    project = example.site
    settings-template-extension = templates/settings-extension.py.in
    media-origin = satchmo_store:../static
    media-url = static
    admin-media = media
    template-loaders = 
        django.template.loaders.filesystem.load_template_source
        django.template.loaders.app_directories.load_template_source
    middleware =
        django.middleware.common.CommonMiddleware
        django.contrib.sessions.middleware.SessionMiddleware
        django.middleware.locale.LocaleMiddleware
        django.contrib.auth.middleware.AuthenticationMiddleware
        django.middleware.doc.XViewMiddleware
        threaded_multihost.middleware.ThreadLocalMiddleware
        satchmo_store.shop.SSLMiddleware.SSLRedirect
    template-context-processors =
        satchmo_store.shop.context_processors.settings
        django.core.context_processors.auth
    apps=
        django.contrib.sites
        satchmo_store.shop
        django.contrib.admin
        django.contrib.auth
        django.contrib.contenttypes
        django.contrib.comments
        django.contrib.sessions
        django.contrib.sitemaps
        registration
        sorl.thumbnail
        keyedcache
        livesettings
        l10n
        satchmo_utils.thumbnail
        satchmo_store.contact
        tax
        tax.modules.no
        tax.modules.area
        tax.modules.percent
        shipping
        product
        payment
        payment.modules.dummy
        satchmo_ext.satchmo_toolbar
        satchmo_utils
        app_plugins
        product.modules.configurable
    authentication-backends =
        satchmo_store.accounts.email-auth.EmailBackend
        django.contrib.auth.backends.ModelBackend
    languages =
        en English
        it Italiano
    language-code = en-us
    timezone = Europe/Rome
    site-name = Satchmo Sample Site
    site-domain = localhost
    site-id = 1
    debug = true
    
    [versions]
    PIL = 1.1.7
    trml2pdf = 0.1
    Satchmo = 0.9-1

As you can see, a lot more options are used, including an extension template
(the default template with appended the given template).

See Options_, `Default template options`_ and `Example usage`_ for more
details.

Links
*****

- Code repository: http://gitorious.org/djc-recipe/djc-recipe
- Report bugs at http://open.abstract.it/it/progetti/rilasci-abstract/djc.recipe/issues
- Comments and questions at info@abstract.it

.. _Django: http://www.djangoproject.com/
.. _`zc.buildout`: http://www.buildout.org/
.. _Satchmo: http://www.satchmoproject.com

