Fixed #18637 - Updated some documentation for aspects of models that are ModelForm specific, not admin specific.

Thanks Ben Sturmfels for the patch.

docs/ref/models/fields.txt

@@ -70,8 +70,8 @@ If ``True``, the field is allowed to be blank. Default is ``False``.
 
 Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is
 purely database-related, whereas :attr:`~Field.blank` is validation-related. If
-a field has ``blank=True``, validation on Django's admin site will allow entry
+a field has ``blank=True``, form validation will allow entry of an empty value.
-of an empty value. If a field has ``blank=False``, the field will be required.
+If a field has ``blank=False``, the field will be required.
 
 .. _field-choices:
 
@@ -81,14 +81,11 @@ of an empty value. If a field has ``blank=False``, the field will be required.
 .. attribute:: Field.choices
 
 An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
-field.
+field. If this is given, the default form widget will be a select box with
+these choices instead of the standard text field.
 
-If this is given, Django's admin will use a select box instead of the standard
+The first element in each tuple is the actual value to be stored, and the
-text field and will limit choices to the choices given.
+second element is the human-readable name. For example::
-
-A choices list is an iterable of 2-tuples; the first element in each
-tuple is the actual value to be stored, and the second element is the
-human-readable name. For example::
 
     YEAR_IN_SCHOOL_CHOICES = (
         ('FR', 'Freshman'),
@@ -203,8 +200,8 @@ callable it will be called every time a new object is created.
 
 .. attribute:: Field.editable
 
-If ``False``, the field will not be editable in the admin or via forms
+If ``False``, the field will not be displayed in the admin or any other
-automatically generated from the model class. Default is ``True``.
+:class:`~django.forms.ModelForm`. Default is ``True``.
 
 ``error_messages``
 ------------------
@@ -224,11 +221,11 @@ the `Field types`_ section below.
 
 .. attribute:: Field.help_text
 
-Extra "help" text to be displayed under the field on the object's admin form.
+Extra "help" text to be displayed with the form widget. It's useful for
-It's useful for documentation even if your object doesn't have an admin form.
+documentation even if your field isn't used on a form.
 
-Note that this value is *not* HTML-escaped when it's displayed in the admin
+Note that this value is *not* HTML-escaped in automatically-generated
-interface. This lets you include HTML in :attr:`~Field.help_text` if you so
+forms. This lets you include HTML in :attr:`~Field.help_text` if you so
 desire. For example::
 
     help_text="Please use the following format: <em>YYYY-MM-DD</em>."
@@ -259,7 +256,7 @@ Only one primary key is allowed on an object.
 
 If ``True``, this field must be unique throughout the table.
 
-This is enforced at the database level and at the Django admin-form level. If
+This is enforced at the database level and by model validation. If
 you try to save a model with a duplicate value in a :attr:`~Field.unique`
 field, a :exc:`django.db.IntegrityError` will be raised by the model's
 :meth:`~django.db.models.Model.save` method.
@@ -279,7 +276,7 @@ For example, if you have a field ``title`` that has
 ``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two
 records with the same ``title`` and ``pub_date``.
 
-This is enforced at the Django admin-form level but not at the database level.
+This is enforced by model validation but not at the database level.
 
 ``unique_for_month``
 --------------------
@@ -337,7 +334,7 @@ otherwise. See :ref:`automatic-primary-key-fields`.
 
 A 64 bit integer, much like an :class:`IntegerField` except that it is
 guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The
-admin represents this as an ``<input type="text">`` (a single-line input).
+default form widget for this field is a :class:`~django.forms.TextInput`.
 
 
 ``BooleanField``
@@ -347,7 +344,8 @@ admin represents this as an ``<input type="text">`` (a single-line input).
 
 A true/false field.
 
-The admin represents this as a checkbox.
+The default form widget for this field is a
+:class:`~django.forms.CheckboxInput`.
 
 If you need to accept :attr:`~Field.null` values then use
 :class:`NullBooleanField` instead.
@@ -361,7 +359,7 @@ A string field, for small- to large-sized strings.
 
 For large amounts of text, use :class:`~django.db.models.TextField`.
 
-The admin represents this as an ``<input type="text">`` (a single-line input).
+The default form widget for this field is a :class:`~django.forms.TextInput`.
 
 :class:`CharField` has one extra required argument:
 
@@ -414,9 +412,10 @@ optional arguments:
     for creation of timestamps. Note that the current date is *always* used;
     it's not just a default value that you can override.
 
-The admin represents this as an ``<input type="text">`` with a JavaScript
+The default form widget for this field is a
-calendar, and a shortcut for "Today". Includes an additional ``invalid_date``
+:class:`~django.forms.TextInput`. The admin adds a JavaScript calendar,
-error message key.
+and a shortcut for "Today". Includes an additional ``invalid_date`` error
+message key.
 
 .. note::
     As currently implemented, setting ``auto_now`` or ``auto_now_add`` to
@@ -431,8 +430,9 @@ error message key.
 A date and time, represented in Python by a ``datetime.datetime`` instance.
 Takes the same extra arguments as :class:`DateField`.
 
-The admin represents this as two ``<input type="text">`` fields, with
+The default form widget for this field is a single
-JavaScript shortcuts.
+:class:`~django.forms.TextInput`. The admin uses two separate
+:class:`~django.forms.TextInput` widgets with JavaScript shortcuts.
 
 ``DecimalField``
 ----------------
@@ -461,7 +461,7 @@ decimal places::
 
     models.DecimalField(..., max_digits=19, decimal_places=10)
 
-The admin represents this as an ``<input type="text">`` (a single-line input).
+The default form widget for this field is a :class:`~django.forms.TextInput`.
 
 .. note::
 
@@ -539,8 +539,8 @@ Also has one optional argument:
     Optional. A storage object, which handles the storage and retrieval of your
     files. See :doc:`/topics/files` for details on how to provide this object.
 
-The admin represents this field as an ``<input type="file">`` (a file-upload
+The default form widget for this field is a
-widget).
+:class:`~django.forms.widgets.FileInput`.
 
 Using a :class:`FileField` or an :class:`ImageField` (see below) in a model
 takes a few steps:
@@ -725,7 +725,7 @@ can change the maximum length using the :attr:`~CharField.max_length` argument.
 
 A floating-point number represented in Python by a ``float`` instance.
 
-The admin represents this as an ``<input type="text">`` (a single-line input).
+The default form widget for this field is a :class:`~django.forms.TextInput`.
 
 .. _floatfield_vs_decimalfield:
 
@@ -776,16 +776,16 @@ length using the :attr:`~CharField.max_length` argument.
 
 .. class:: IntegerField([**options])
 
-An integer. The admin represents this as an ``<input type="text">`` (a
+An integer. The default form widget for this field is a
-single-line input).
+:class:`~django.forms.TextInput`.
 
 ``IPAddressField``
 ------------------
 
 .. class:: IPAddressField([**options])
 
-An IP address, in string format (e.g. "192.0.2.30"). The admin represents this
+An IP address, in string format (e.g. "192.0.2.30"). The default form widget
-as an ``<input type="text">`` (a single-line input).
+for this field is a :class:`~django.forms.TextInput`.
 
 ``GenericIPAddressField``
 -------------------------
@@ -795,8 +795,8 @@ as an ``<input type="text">`` (a single-line input).
 .. versionadded:: 1.4
 
 An IPv4 or IPv6 address, in string format (e.g. ``192.0.2.30`` or
-``2a02:42fe::4``). The admin represents this as an ``<input type="text">``
+``2a02:42fe::4``). The default form widget for this field is a
-(a single-line input).
+:class:`~django.forms.TextInput`.
 
 The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2,
 including using the IPv4 format suggested in paragraph 3 of that section, like
@@ -823,8 +823,8 @@ are converted to lowercase.
 .. class:: NullBooleanField([**options])
 
 Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use
-this instead of a :class:`BooleanField` with ``null=True``. The admin represents
+this instead of a :class:`BooleanField` with ``null=True``. The default form
-this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
+widget for this field is a :class:`~django.forms.NullBooleanSelect`.
 
 ``PositiveIntegerField``
 ------------------------
@@ -875,8 +875,8 @@ Like an :class:`IntegerField`, but only allows values under a certain
 
 .. class:: TextField([**options])
 
-A large text field. The admin represents this as a ``<textarea>`` (a multi-line
+A large text field. The default form widget for this field is a
-input).
+:class:`~django.forms.Textarea`.
 
 .. admonition:: MySQL users
 
@@ -893,8 +893,8 @@ input).
 A time, represented in Python by a ``datetime.time`` instance. Accepts the same
 auto-population options as :class:`DateField`.
 
-The admin represents this as an ``<input type="text">`` with some JavaScript
+The default form widget for this field is a :class:`~django.forms.TextInput`.
-shortcuts.
+The admin adds some JavaScript shortcuts.
 
 ``URLField``
 ------------
@@ -903,7 +903,7 @@ shortcuts.
 
 A :class:`CharField` for a URL.
 
-The admin represents this as an ``<input type="text">`` (a single-line input).
+The default form widget for this field is a :class:`~django.forms.TextInput`.
 
 Like all :class:`CharField` subclasses, :class:`URLField` takes the optional
 :attr:`~CharField.max_length`argument. If you don't specify
@@ -979,9 +979,9 @@ define the details of how the relation works.
 .. attribute:: ForeignKey.limit_choices_to
 
     A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`)
-    that limit the available admin choices for this object. Use this with
+    that limit the available admin or ModelForm choices for this object. Use
-    functions from the Python ``datetime`` module to limit choices of objects by
+    this with functions from the Python ``datetime`` module to limit choices of
-    date. For example::
+    objects by date. For example::
 
         limit_choices_to = {'pub_date__lte': datetime.now}
 

docs/topics/db/models.txt

@@ -108,8 +108,8 @@ determine a few things:
 
 * The database column type (e.g. ``INTEGER``, ``VARCHAR``).
 
-* The :doc:`widget </ref/forms/widgets>` to use in Django's admin interface,
+* The default :doc:`widget </ref/forms/widgets>` to use when rendering a form
-  if you care to use it (e.g. ``<input type="text">``, ``<select>``).
+  field (e.g. ``<input type="text">``, ``<select>``).
 
 * The minimal validation requirements, used in Django's admin and in
   automatically-generated forms.
@@ -143,13 +143,13 @@ ones:
     Note that this is different than :attr:`~Field.null`.
     :attr:`~Field.null` is purely database-related, whereas
     :attr:`~Field.blank` is validation-related. If a field has
-    :attr:`blank=True <Field.blank>`, validation on Django's admin site will
+    :attr:`blank=True <Field.blank>`, form validation will
     allow entry of an empty value. If a field has :attr:`blank=False
     <Field.blank>`, the field will be required.
 
 :attr:`~Field.choices`
     An iterable (e.g., a list or tuple) of 2-tuples to use as choices for
-    this field. If this is given, Django's admin will use a select box
+    this field. If this is given, the default form widget will be a select box
     instead of the standard text field and will limit choices to the choices
     given.
 
@@ -164,7 +164,7 @@ ones:
         )
 
     The first element in each tuple is the value that will be stored in the
-    database, the second element will be displayed by the admin interface,
+    database, the second element will be displayed by the default form widget
     or in a ModelChoiceField. Given an instance of a model object, the
     display value for a choices field can be accessed using the
     ``get_FOO_display`` method. For example::
@@ -195,9 +195,8 @@ ones:
     created.
 
 :attr:`~Field.help_text`
-    Extra "help" text to be displayed under the field on the object's admin
+    Extra "help" text to be displayed with the form widget. It's useful for
-    form. It's useful for documentation even if your object doesn't have an
+    documentation even if your field isn't used on a form.
-    admin form.
 
 :attr:`~Field.primary_key`
     If ``True``, this field is the primary key for the model.
@@ -360,13 +359,12 @@ It doesn't matter which model has the
 :class:`~django.db.models.ManyToManyField`, but you should only put it in one
 of the models -- not both.
 
-Generally, :class:`~django.db.models.ManyToManyField` instances should go in the
+Generally, :class:`~django.db.models.ManyToManyField` instances should go in
-object that's going to be edited in the admin interface, if you're using
+the object that's going to be edited on a form. In the above example,
-Django's admin. In the above example, ``toppings`` is in ``Pizza`` (rather than
+``toppings`` is in ``Pizza`` (rather than ``Topping`` having a ``pizzas``
-``Topping`` having a ``pizzas`` :class:`~django.db.models.ManyToManyField` )
+:class:`~django.db.models.ManyToManyField` ) because it's more natural to think
-because it's more natural to think about a pizza having toppings than a
+about a pizza having toppings than a topping being on multiple pizzas. The way
-topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
+it's set up above, the ``Pizza`` form would let users select the toppings.
-form would let users select the toppings.
 
 .. seealso::