Browse Source

Fixed #25748 -- Added clarification on projects vs. applications.

Thanks Thomas Güttler for motivating this addition.
Tim Graham 9 years ago
parent
commit
e051930123
1 changed files with 15 additions and 7 deletions
  1. 15 7
      docs/ref/applications.txt

+ 15 - 7
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 </intro/reusable-apps/>` 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