From e0519301238b43633bab64054772f9a62634a05f Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Thu, 24 Dec 2015 09:47:45 -0500 Subject: [PATCH] Fixed #25748 -- Added clarification on projects vs. applications. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks Thomas Güttler for motivating this addition. --- docs/ref/applications.txt | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index 833ec12e34..87004a7afa 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -18,15 +18,19 @@ This registry is simply called :attr:`~django.apps.apps` and it's available in Projects and applications ========================= -Django has historically used the term **project** to describe an installation -of Django. A project is defined primarily by a settings module. +The term **project** describes a Django web application. The project Python +package is defined primarily by a settings module, but it usually contains +other things. For example, when you run ``django-admin startproject mysite`` +you'll get a ``mysite`` project directory that contains a ``mysite`` Python +package with ``settings.py``, ``urls.py``, and ``wsgi.py``. The project package +is often extended to include things like fixtures, CSS, and templates which +aren't tied to a particular application. The term **application** describes a Python package that provides some set of -features. Applications may be reused in various projects. - -.. note:: - This terminology is somewhat confusing these days as it became common to - use the phrase "web app" to describe what equates to a Django project. +features. Applications :doc:`may be reused ` in various +projects. A project's root directory (the one that contains ``manage.py``) is +usually the container for all of a project's applications which aren't +installed separately. Applications include some combination of models, views, templates, template tags, static files, URLs, middleware, etc. They're generally wired into @@ -41,6 +45,10 @@ interact with installed applications, mainly for configuration and also for introspection. That's why the application registry maintains metadata in an :class:`~django.apps.AppConfig` instance for each installed application. +There's no restriction that a project package can't also be considered an +application and have models, etc. (which would require adding it to +:setting:`INSTALLED_APPS`). + .. _configuring-applications-ref: Configuring applications