Ticket #35831 Include ModelForm and its Meta options in reference docs, follow up on PR #18699 #19758

mspirbhai · 2025-08-21T10:08:52Z

Trac ticket number

ticket-35831

Branch description

Follow up on @jernwerber work on the ticket from PR #18699.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

…k target to the ModelForm topic entry.

…y functions. Reworked text based on PR feedback.

options and Factory functions. Reworked text based on PR feedback.

Co-authored-by: Tim Schilling <schilling711@gmail.com>

github-actions

Hello! Thank you for your contribution 💪

As it's your first contribution be sure to check out the patch review checklist.

If you're fixing a ticket from Trac make sure to set the "Has patch" flag and include a link to this PR in the ticket!

If you have any design or process questions then you can ask in the Django forum.

Welcome aboard ⛵️!

sarahboyce

Thank you for picking this up @mspirbhai !

Once you have reverted the changes in docs/conf.py, can you squash to a single commit with yourself and @jernwerber as the co-author?

I have re-read through and tried to make suggestions with the following in mind:

consistency of phrasing
"less is more": occasionally there were references around potential errors raised when not configured correctly. I have sometimes opted to remove this and focus on documenting how to configure correctly.

I have broken up these suggestions so if you disagree with any of the changes, shout 👍

sarahboyce · 2025-08-22T07:37:03Z

docs/conf.py

Please revert changes in this file as they do not relate to ticket-35831

sarahboyce · 2025-08-22T07:47:36Z

docs/ref/forms/models.txt

+.. class:: ModelForm
+
+.. _ref-modelform:
+


Suggested change

.. class:: ModelForm

.. _ref-modelform:

sarahboyce · 2025-08-22T07:47:51Z

docs/ref/forms/models.txt

+.. _ref-modelform-meta-options:
+


Suggested change

.. _ref-modelform-meta-options:

sarahboyce · 2025-08-22T09:29:53Z

docs/ref/forms/models.txt

+.. currentmodule:: django.forms
+
+:class:`~django.forms.ModelForm` API reference. For introductory material about
+ModelForms, see the :doc:`/topics/forms/modelforms` topic guide.


Suggested change

ModelForms, see the :doc:`/topics/forms/modelforms` topic guide.

using a ``ModelForm``, see the :doc:`/topics/forms/modelforms` topic guide.

sarahboyce · 2025-08-22T09:30:26Z

docs/ref/forms/models.txt

+The ``_meta`` API is used to build forms that reflect a Django model. The API
+is accessible through the ``_meta`` attribute of each model form, which is an
+instance of a ``django.forms.models.ModelFormOptions`` object.
+The exact structure of the form produced can be controlled by setting metadata
+options as attributes of an inner ``Meta`` class.
+
+Here is an example using some sort of Book model::


Suggested change

The ``_meta`` API is used to build forms that reflect a Django model. The API

is accessible through the ``_meta`` attribute of each model form, which is an

instance of a ``django.forms.models.ModelFormOptions`` object.

The exact structure of the form produced can be controlled by setting metadata

options as attributes of an inner ``Meta`` class.

Here is an example using some sort of Book model::

The ``_meta`` API is used to build forms that reflect a Django model. It is

accessible through the ``_meta`` attribute of each model form, and is an

``django.forms.models.ModelFormOptions`` instance.

The structure of the generated form can be customized by defining metadata

options as attributes of an inner ``Meta`` class. For example::

(perhaps)

sarahboyce · 2025-08-22T09:34:26Z

docs/ref/forms/models.txt

+    A dictionary that maps a model field name string to a help text
+    string. 
+
+    Where a field doesn't have a label string mapped to it in
+    :attr:`~ModelFormOptions.help_texts`, Django will fall back on that model
+    field's :attr:`~django.db.models.Field.help_text`.


Suggested change

A dictionary that maps a model field name string to a help text

string.

Where a field doesn't have a label string mapped to it in

:attr:`~ModelFormOptions.help_texts`, Django will fall back on that model

field's :attr:`~django.db.models.Field.help_text`.

A dictionary that maps a model field name to a help text string.

When a field is not specified, Django will fall back on that model field's

:attr:`~django.db.models.Field.help_text`.

sarahboyce · 2025-08-22T09:34:41Z

docs/ref/forms/models.txt

+    A dictionary that maps a model field name string to a label string. 
+
+    Where a field doesn't have a label string mapped to it in
+    :attr:`~ModelFormOptions.labels`, Django will fall back on that model
+    field's :attr:`~django.db.models.Field.verbose_name` and then the field's
+    attribute name.


Suggested change

A dictionary that maps a model field name string to a label string.

Where a field doesn't have a label string mapped to it in

:attr:`~ModelFormOptions.labels`, Django will fall back on that model

field's :attr:`~django.db.models.Field.verbose_name` and then the field's

attribute name.

A dictionary that maps a model field names to a label string.

When a field is not specified, Django will fall back on that model field's

:attr:`~django.db.models.Field.verbose_name` and then the field's attribute

name.

sarahboyce · 2025-08-22T09:34:54Z

docs/ref/forms/models.txt

+    A tuple of strings or a list of strings that are field names.
+
+    The fields included in this list will have their data localized (by default,
+    the form fields output by a :class:`~django.forms.ModelForm` are **not**
+    localized, see :ref:`Creating forms from models: Enabling localization of
+    fields <modelforms-enabling-localization-of-fields>`).  
+
+    Like :attr:`~ModelFormOptions.fields`,
+    :attr:`~ModelFormOptions.localized_fields` can be set to the special string
+    ``'__all__'`` to include all fields.


Suggested change

A tuple of strings or a list of strings that are field names.

The fields included in this list will have their data localized (by default,

the form fields output by a :class:`~django.forms.ModelForm` are **not**

localized, see :ref:`Creating forms from models: Enabling localization of

fields <modelforms-enabling-localization-of-fields>`).

Like :attr:`~ModelFormOptions.fields`,

:attr:`~ModelFormOptions.localized_fields` can be set to the special string

``'__all__'`` to include all fields.

A tuple or list of :attr:`~ModelFormOptions.model` field names to be

localized. The value ``'__all__'`` can be used to specify that all fields

should be localized.

By default, form fields are not localized, see

:ref:`enabling localization of fields

<modelforms-enabling-localization-of-fields>` for more details.

sarahboyce · 2025-08-22T09:35:18Z

docs/ref/forms/models.txt

+    *Required.* A :class:`django.db.models.Model` to be used for this
+    :class:`~django.forms.ModelForm`.
+
+    If no class is specified, a :exc:`ValueError` exception will be raised.


Suggested change

*Required.* A :class:`django.db.models.Model` to be used for this

:class:`~django.forms.ModelForm`.

If no class is specified, a :exc:`ValueError` exception will be raised.

Required. The :class:`django.db.models.Model` to be used for the

:class:`~django.forms.ModelForm`.

sarahboyce · 2025-08-22T09:35:34Z

docs/ref/forms/models.txt

+    A dictionary that maps a model field name string to a
+    :class:`django.forms.Widget`. 
+
+    Where an included model field doesn't have a widget mapped to it in
+    :attr:`~ModelFormOptions.widgets`, Django will fall back on the default
+    widget for that particular type of :class:`django.db.models.Field`.


Suggested change

A dictionary that maps a model field name string to a

:class:`django.forms.Widget`.

Where an included model field doesn't have a widget mapped to it in

:attr:`~ModelFormOptions.widgets`, Django will fall back on the default

widget for that particular type of :class:`django.db.models.Field`.

A dictionary that maps a model field name to a

:class:`django.forms.Widget`.

When a field is not specified, Django will fall back on the default widget

for that particular type of :class:`django.db.models.Field`.

jernwerber and others added 10 commits October 21, 2024 23:18

Created reference entry for ModelForm's inner Meta class. Added a lin…

76ea410

…k target to the ModelForm topic entry.

Restructured ref/forms/models to contain both Meta options and Factor…

e2da674

…y functions. Reworked text based on PR feedback.

Restructured ref/forms/models to contain both Meta

1306481

options and Factory functions. Reworked text based on PR feedback.

Changed 'mistyped' to 'typos' for spellcheck.

e5cc6a6

Further edits to page structure & fixed CI errors.

14b4149

Small refinement to text

5695568

Merge branch 'django:main' into ticket_35831

ba6a74d

Applying some fixes from review

b8935b5

Co-authored-by: Tim Schilling <schilling711@gmail.com>

Fixing text flow around changes from review.

3cfc526

Fixed the review items from django#18699 for docs/ref/forms/models.txt.

71145e0

github-actions bot reviewed Aug 21, 2025

View reviewed changes

mspirbhai added 2 commits August 21, 2025 13:25

Fixed line 24 for docutils warning by adding blank line after directive.

7943796

Update conf.py

209bb2c

sarahboyce reviewed Aug 22, 2025

View reviewed changes

sarahboyce mentioned this pull request Aug 22, 2025

Ticket #35831 Include ModelForm and its Meta options in reference docs #18699

Closed

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Ticket #35831 Include ModelForm and its Meta options in reference docs, follow up on PR #18699 #19758

Ticket #35831 Include ModelForm and its Meta options in reference docs, follow up on PR #18699 #19758

Uh oh!

mspirbhai commented Aug 21, 2025

Uh oh!

github-actions bot left a comment

Uh oh!

sarahboyce left a comment

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

sarahboyce Aug 22, 2025

Uh oh!

Uh oh!

	ModelForms, see the :doc:`/topics/forms/modelforms` topic guide.
	using a ``ModelForm``, see the :doc:`/topics/forms/modelforms` topic guide.

Uh oh!

Ticket #35831 Include ModelForm and its Meta options in reference docs, follow up on PR #18699 #19758

Are you sure you want to change the base?

Ticket #35831 Include ModelForm and its Meta options in reference docs, follow up on PR #18699 #19758

Uh oh!

Conversation

mspirbhai commented Aug 21, 2025

Trac ticket number

Branch description

Checklist

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!