{% comment %}

Django Project Package Template

This is a template for a Django 2.x project.

The project has a layout so that it can be build as a wheel, one type of Python packages.

Features

setup() is configured using a setup.cfg file.
The version is defined in {{ project_name }}.__version__.
Source code is located in a src directory to prevent side effects.
All apps use the {{ project_name }}.apps namespace.
All configuration modules use the {{ project_name }}.conf namespace.
{{ project_name }}.conf.settings uses pathlib instead of os and os.path.
Many settings can be defined using environment variables and parsed with envparse.
All templates, static files and locales will be included in the wheel.
All code follows the Black code style.
All docstrings follow PEP 257 conventions.
Django Debug Toolbar, IPython and check-manifest are already added to the development dependencies.
A Sublime Text project configuration is already included.

Usage

Use the following startproject command to create a new project using this template:

python3 -m django startproject --extension=cfg,gitignore,gitkeep,in,md,sublime-project \
    --template=https://github.com/keimlink/django-project-package-template/archive/master.zip \
    name [directory]

Tip: If you want to create the project in your current working directory use . as directory argument.

Testbed

A testbed to quickly test the project template can be found in the separate django-project-package-template-testbed repository.

License

Distributed under the MIT License.

All text below the horizontal line is the template for the new project's README.

{% endcomment %}# {{ project_name|title }}

Describe your project in one sentence.

Quickstart

Install the project and the development dependencies into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install --editable ".[dev]"
./manage.py migrate
./manage.py createsuperuser
./manage.py runserver

Starting a New App

First create a new directory in the apps directory:

mkdir src/{{ project_name }}/apps/name

Then pass the path to the new directory to the [startapp](https://docs.djangoproject.com/en/{{ docs_version }}/ref/django-admin/#django-admin-startapp) command:

./manage.py startapp name src/{{ project_name }}/apps/name

Deployment

The following list describes only the absolute necessary steps to outline a deployment for a Django project wheel. For example a component to serve static files is missing - you could use WhiteNoise to do this.

Also see [How to use Django with Gunicorn](https://docs.djangoproject.com/en/{{ docs_version }}/howto/deployment/wsgi/gunicorn/) and [Deployment Checklist](https://docs.djangoproject.com/en/{{ docs_version }}/howto/deployment/checklist/) for more information.

Add your favorite WSGI HTTP server, e.g. Gunicorn, to install_requires in setup.cfg.
Check if all files are included in the package:
```
check-manifest
```
Build a wheel of the project.
```
./setup.py bdist_wheel
```
Copy the wheel file from the dist directory to the server to be deployed.

Create a minimal configuration on the server using environment variables.

export DJANGO_SETTINGS_MODULE={{ project_name }}.conf.settings
export DJANGO_ALLOWED_HOSTS=www.example.com
export DJANGO_DEBUG=False

Install the wheel and [collect the static files](https://docs.djangoproject.com/en/{{ docs_version }}/ref/contrib/staticfiles/#django-admin-collectstatic):
```
python3 -m pip install --find-links=/path/to/wheel_dir {{ project_name }}
django-project collectstatic --no-input
```
Start Gunicorn like this:
```
gunicorn {{ project_name }}.wsgi
```

keimlink / django-project-package-template

readme