A Cookiecutter template that contains everything you need to develop a Django site. The template lays out the project, adds tools to support development and testing and configures the site with essential infrastructure.
The template generates a complete working site right out of the box. All the features are optional so you get what you need and none of the things you didn't want.
- Generate a working Django site right of the box.
- Code checking with flake8 or pylama.
- Code formatting with black and isort.
- Automatically add project configuration to PyCharm.
- Automatically activate the virtualenv with direnv.
- Manage package versions and the virtualenv with pip-tools.
- Manage repetitive project tasks with make.
- Configure the site to use a CMS such as Wagtail
- Configure the site to run background and periodic tasks with Celery.
- Configure the site to log errors with Sentry.
- Configure the site to log structured data with structlog and django-structlog.
- Colour output written to the console with colorama
- Run tests for all supported environments using tox.
- Publish documentation to Read the Docs.
- Profile and debug requests using django-debug-toolbar.
- Testing pushes and pull requests with GitHub Actions.
Ensure you have cookiecutter installed:
pip install --user cookiecutter
Change to the directory where the project will be generated:
cd ~/Development
Then use cookiecutter to generate your project from this template with:
cookiecutter gh:StuartMacKay/cookiecutter-django-site
Answer all the configuration options and you are good to go:
cd <my new site> python manage.py migrate python manage.py createsuperuser python manage.py runserver
To generate the project you will be asked for the following fields, in order:
| Field | Default | Description |
|---|---|---|
| site_name | Django MySite | The project's official or human-readable name. |
| site_dir | django-mysite | This is the name for the project's root directory. Generally this is also the name of the project for the repository. |
| site_app | project | The name of the Django app that contains the settings etc. "project" is used as there is no real need to use a project specific name as it's not imported anywhere. |
| repository_url | <blank> | The URL used to checkout the code, for example: git@github.com:StuartMacKay/cookiecutter-django-site.git. Leave blank if you do not want to set up the repository right away. |
| python_version | 3.8 | The version of the python interpreter to use. This is used in the Makefile when creating the virtualenv for the project. |
| author | Author's full name | Main author of this site. This can also be the name of an organisation. |
| author_email | Author's email address | The email address of the main point of contact for the project. This is also used as the point of contact in licenses and copyright notices. |
| create_makefile | y | Add a (GNU Make) Makefile to automate project tasks. |
| create_virtualenv | y | Create the virtualenv and install the requirements when the project is generated. |
| ide | pycharm | Create the configuration files for an Integrated Development Environment. The list of choices includes:
PyCharm is configured with targets for running the site, celery and celery beat. You will need to install a plugin for .env files. |
| code_linter | flake8 | Tools for checking code quality. The list of choices includes: |
| use_black | y | Use black for formatting the source files in project. |
| use_isort | y | Use isort for organising the import statements in your source files. |
| use_readthedocs | y | Generate project documentation, using Sphinx, that can be hosted on Read The Docs. |
| use_coverage | y | Check the quality of your tests using coverage. |
| sphinx_theme | sphinx-rtd-theme | The theme to use when generating the docs for Read the Docs. The list of choices includes:
The theme is only used if |
| test_runner | django | The test runner to use. Available options include:
Nose has been on maintenance since 2015 so it is not included here. There does seem to be a follow-up project, nose2, but it's not clear how much life it has right now. |
| cms | none | Install a django-based content management system. Available options include:
|
| use_celery | y | Use Celery for running and scheduling tasks in the background. |
| use_debug_toolbar | y | Use django-debug-toolbar for displaying debug information the current request/response. |
| use_sentry | y | Use Sentry for logging errors on staging and production. |
| use_structlog | y | Use structlog and django-structlog for logging structured data on staging and production. Console output is prettified with colorama. |
See the CHANGELOG.rst for a complete history of changes and what is currently being prepared for release.
See the ROADMAP.rst for details on what's coming.