cookiecutter-django ======================= A cookiecutter_ template for Django. .. _cookiecutter: https://github.com/audreyr/cookiecutter Features --------- * For Django 1.6 * Twitter Bootstrap_ 3 * AngularJS_ * Settings management via django-configurations_ * Registration via django-allauth_ * User avatars via django-avatar_ * Procfile_ for deploying to Heroku * Heroku optimized requirements * Basic caching setup * Grunt build for compass and livereload * 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/ Constraints ----------- * Only maintained 3rd party libraries are used. * PostgreSQL everywhere * Environment variables for configuration (This won't work with Apache/mod_wsgi). Usage ------ 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. First, get cookiecutter. Trust me, it's awesome:: $ pip install cookiecutter Now run it against this repo:: $ cookiecutter https://github.com/pydanny/cookiecutter-django.git 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:: Cloning into 'cookiecutter-django'... 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. project_name (default is "project_name")? Reddit Clone repo_name (default is "repo_name")? redditclone 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. year (default is "Current year")? 2014 domain_name (default is "Domain name")? Enter the project and take a look around:: $ cd redditclone/ $ ls Create a GitHub repo and push it there:: $ git init $ git add . $ git commit -m "first awesome commit" $ git remote add origin git@github.com:pydanny/redditclone.git $ git push -u origin master Now take a look at your repo. Don't forget to carefully look at the generated README. Awesome, right? 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 First make sure to create and activate a virtualenv_, then open a terminal at the project root and install the requirements for local development:: $ pip install -r requirements/local.txt .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/ 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** 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 .. _nodejs: http://nodejs.org/download/ 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. To get live reloading to work you'll probably need to install an `appropriate browser extension`_ .. _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!!! "Your Stuff" ------------- 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. Releases -------- Want a stable release? You can find them at https://github.com/pydanny/cookiecutter-django/releases **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 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 (cookiecutter) $ git clone https://github.com/audreyr/cookiecutter.git (cookiecutter) cd cookiecutter (cookiecutter) python setup.py develop Not Exactly What You Want? --------------------------- This is what I want. *It might not be what you want.* Don't worry, you have options: 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: * cookiecutter_ so it gets listed in the README as a template. * 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 experience better.