[1.9.x] Fixed #25127 -- Documented how to organize models in a package.

Backport of 84d8d1d7151a4ee70ae35037d37f76a40d18da64 from master

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 93db3b1e71..738f5aace6 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -1366,6 +1366,30 @@ different database tables).
 Django will raise a :exc:`~django.core.exceptions.FieldError` if you override
 any model field in any ancestor model.
 
+Organizing models in a package
+==============================
+
+The :djadmin:`manage.py startapp <startapp>` command creates an application
+structure that includes a ``models.py`` file. If you have many models,
+organizing them in separate files may be useful.
+
+To do so, create a ``models`` package. Remove ``models.py`` and create a
+``myapp/models/`` directory with an ``__init__.py`` file and the files to
+store your models. You must import the models in the ``__init__.py`` file.
+
+For example, if you had ``organic.py`` and ``synthetic.py`` in the ``models``
+directory:
+
+.. snippet::
+    :filename: myapp/models/__init__.py
+
+    from .organic import Person
+    from .synthetic import Robot
+
+Explicitly importing each model rather than using ``from .models import *``
+has the advantages of not cluttering the namespace, making code more readable,
+and keeping code analysis tools useful.
+
 .. seealso::
 
     :doc:`The Models Reference </ref/models/index>`