2013-08-20 13:21:08 +04:00
cookiecutter-django
2013-08-15 22:32:13 +04:00
=======================
2014-08-17 18:23:19 +04:00
.. image :: https://requires.io/github/pydanny/cookiecutter-django/requirements.png?branch=master
:target: https://requires.io/github/pydanny/cookiecutter-django/requirements/?branch=master
:alt: Requirements Status
2013-08-15 22:32:13 +04:00
A cookiecutter_ template for Django.
.. _cookiecutter: https://github.com/audreyr/cookiecutter
2013-08-16 15:03:11 +04:00
Features
---------
2013-12-17 20:47:37 +04:00
* For Django 1.6
2014-05-02 23:49:26 +04:00
* Twitter Bootstrap_ 3
* AngularJS_
* Settings management via django-configurations_
* Registration via django-allauth_
* User avatars via django-avatar_
* Procfile_ for deploying to Heroku
2013-08-16 15:03:11 +04:00
* Heroku optimized requirements
2013-08-16 15:35:18 +04:00
* Basic caching setup
2014-01-10 01:03:28 +04:00
* Grunt build for compass and livereload
2014-05-02 23:49:26 +04:00
* Basic e-mail configurations for send emails via SendGrid_
.. _Bootstrap: https://github.com/twbs/bootstrap
.. _AngularJS: https://github.com/angular/angular.js
.. _django-configurations: https://github.com/jezdez/django-configurations
.. _django-allauth: https://github.com/pennersr/django-allauth
.. _django-avatar: https://github.com/jezdez/django-avatar/
.. _Procfile: https://devcenter.heroku.com/articles/procfile
.. _SendGrid: https://sendgrid.com/
2013-08-16 15:35:18 +04:00
Constraints
-----------
* Only maintained 3rd party libraries are used.
* PostgreSQL everywhere
2013-10-25 18:59:48 +04:00
* Environment variables for configuration (This won't work with Apache/mod_wsgi).
2013-08-16 15:03:11 +04:00
2013-08-20 13:16:39 +04:00
2013-08-18 16:44:28 +04:00
Usage
------
2013-08-16 15:03:11 +04:00
2013-08-18 16:46:20 +04:00
Let's pretend you want to create a Django project called "redditclone". Rather than using `startproject`
and then editing the results to include your name, email, and various configuration issues that always get forgotten until the worst possible moment, get cookiecutter_ to do all the work.
2013-08-18 16:44:28 +04:00
First, get cookiecutter. Trust me, it's awesome::
2013-08-16 15:03:11 +04:00
$ pip install cookiecutter
2013-08-18 16:44:28 +04:00
Now run it against this repo::
2013-08-23 11:55:52 +04:00
$ cookiecutter https://github.com/pydanny/cookiecutter-django.git
2013-08-18 16:44:28 +04:00
You'll be prompted for some questions, answer them, then it will create a Django project for you.
**Warning** : After this point, change 'Daniel Greenfeld', 'pydanny', etc to your own information.
It prompts you for questions. Answer them::
2013-08-23 11:55:52 +04:00
Cloning into 'cookiecutter-django'...
2013-09-13 15:24:45 +04:00
remote: Counting objects: 550, done.
remote: Compressing objects: 100% (310/310), done.
remote: Total 550 (delta 283), reused 479 (delta 222)
Receiving objects: 100% (550/550), 127.66 KiB | 58 KiB/s, done.
Resolving deltas: 100% (283/283), done.
2014-03-22 19:16:11 +04:00
project_name (default is "project_name")? Reddit Clone
2014-01-10 01:03:28 +04:00
repo_name (default is "repo_name")? redditclone
2013-09-13 15:24:45 +04:00
author_name (default is "Your Name")? Daniel Greenfeld
email (default is "Your email")? pydanny@gmail.com
description (default is "A short description of the project.")? A reddit clone.
2014-01-10 12:30:11 +04:00
year (default is "Current year")? 2014
2014-01-10 01:03:28 +04:00
domain_name (default is "Domain name")?
2013-09-13 15:24:45 +04:00
2013-08-18 16:44:28 +04:00
Enter the project and take a look around::
$ cd redditclone/
$ ls
Create a GitHub repo and push it there::
$ git init
$ git add .
2013-09-19 14:02:46 +04:00
$ git commit -m "first awesome commit"
2013-08-18 16:44:28 +04:00
$ git remote add origin git@github.com:pydanny/redditclone.git
$ git push -u origin master
2013-10-25 18:59:48 +04:00
Now take a look at your repo. Don't forget to carefully look at the generated README. Awesome, right?
2013-08-18 16:44:28 +04:00
2014-01-30 00:35:06 +04:00
Getting up and running
----------------------
The steps below will get you up and running with a local development environment. We assume you have the following installed:
* pip
* virtualenv
* PostgreSQL
2014-03-22 19:16:11 +04:00
First make sure to create and activate a virtualenv_, then open a terminal at the project root and install the requirements for local development::
2014-01-30 00:35:06 +04:00
$ pip install -r requirements/local.txt
2014-03-22 19:16:11 +04:00
.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
2014-01-30 00:35:06 +04:00
You can now run the usual Django `` runserver `` command (replace `` yourapp `` with the name of the directory containing the Django project)::
$ python yourapp/manage.py runserver
The base app will run but you'll need to carry out a few steps to make the sign-up and login forms work. These are currently detailed in `issue #39`_ .
.. _issue #39: https://github.com/pydanny/cookiecutter-django/issues/39
**Live reloading and Sass CSS compilation**
2013-09-17 16:21:44 +04:00
2014-01-30 00:35:06 +04:00
If you'd like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with the included Grunt task.
Make sure that nodejs_ is installed. Then in the project root run::
$ npm install
2014-03-22 19:16:11 +04:00
.. _nodejs: http://nodejs.org/download/
2014-01-30 00:35:06 +04:00
Now you just need::
$ grunt serve
The base app will now run as it would with the usual `` manage.py runserver `` but with live reloading and Sass compilation enabled.
2014-03-22 19:16:11 +04:00
To get live reloading to work you'll probably need to install an `appropriate browser extension`_
2014-01-30 00:35:06 +04:00
.. _appropriate browser extension: http://feedback.livereload.com/knowledgebase/articles/86242-how-do-i-install-and-use-the-browser-extensions-
It's time to write the code!!!
2013-08-16 20:23:22 +04:00
"Your Stuff"
-------------
2013-08-17 14:38:23 +04:00
Scattered throughout the Python and HTML of this project are places marked with "your stuff". This is where third-party libraries are to be integrated with your project.
2013-08-18 22:50:39 +04:00
2013-09-17 16:21:44 +04:00
Releases
--------
Want a stable release? You can find them at https://github.com/pydanny/cookiecutter-django/releases
2014-01-10 01:03:28 +04:00
**note** : Cookiecutter won't support tagged releases until 0.7.0 comes out, which should be any day! Which means, if you want to use a
2013-09-17 16:21:44 +04:00
tagged release of cookiecutter-django, then you have to install Cookiecutter directly from GitHub. To do that, follow these steps:
1. Enter your virtualenv.
2. Run these commands:
.. code-block :: bash
2014-01-10 01:03:28 +04:00
2013-09-17 16:21:44 +04:00
(cookiecutter) $ git clone https://github.com/audreyr/cookiecutter.git
(cookiecutter) cd cookiecutter
(cookiecutter) python setup.py develop
2013-08-18 22:50:39 +04:00
Not Exactly What You Want?
---------------------------
2013-08-18 22:53:55 +04:00
This is what I want. *It might not be what you want.* Don't worry, you have options:
2013-08-18 22:50:39 +04:00
Fork This
~~~~~~~~~~
If you have differences in your preferred setup, I encourage you to fork this to create your own version.
Once you have your fork working, let me know and I'll add it to a '*Similar Cookiecutter Templates* ' list here.
It's up to you whether or not to rename your fork.
If you do rename your fork, I encourage you to submit it to the following places:
2014-01-10 01:03:28 +04:00
* cookiecutter_ so it gets listed in the README as a template.
2013-08-18 22:50:39 +04:00
* The cookiecutter grid_ on Django Packages.
.. _cookiecutter: https://github.com/audreyr/cookiecutter
.. _grid: https://www.djangopackages.com/grids/g/cookiecutter/
Or Submit a Pull Request
~~~~~~~~~~~~~~~~~~~~~~~~~
I also accept pull requests on this, if they're small, atomic, and if they make my own project development
2014-01-10 01:03:28 +04:00
experience better.