Refs #32339 -- Deprecated default.html form template.

Co-authored-by: Carlton Gibson <carlton.gibson@noumenal.es>

1 files changed, 43 insertions, 0 deletions

diff --git a/docs/ref/forms/renderers.txt b/docs/ref/forms/renderers.txt
index 8c0263e051..f11b23ab12 100644
--- a/docs/ref/forms/renderers.txt
+++ b/docs/ref/forms/renderers.txt
@@ -56,6 +56,12 @@ should return a rendered templates (as a string) or raise
         Defaults to ``"django/forms/default.html"``, which is a proxy for
         ``"django/forms/table.html"``.
 
+        .. deprecated:: 4.1
+
+        The ``"django/forms/default.html"`` template is deprecated and will be
+        removed in Django 5.0. The default will become
+        ``"django/forms/default.html"`` at that time.
+
     .. attribute:: formset_template_name
 
         .. versionadded:: 4.1
@@ -65,6 +71,12 @@ should return a rendered templates (as a string) or raise
         Defaults to ``"django/forms/formsets/default.html"``, which is a proxy
         for ``"django/forms/formsets/table.html"``.
 
+        .. deprecated:: 4.1
+
+        The ``"django/forms/formset/default.html"`` template is deprecated and
+        will be removed in Django 5.0. The default will become
+        ``"django/forms/formset/div.html"`` template.
+
     .. method:: get_template(template_name)
 
         Subclasses must implement this method with the appropriate template
@@ -97,6 +109,26 @@ If you want to render templates with customizations from your
 :setting:`TEMPLATES` setting, such as context processors for example, use the
 :class:`TemplatesSetting` renderer.
 
+.. class:: DjangoDivFormRenderer
+
+.. versionadded:: 4.1
+
+Subclass of :class:`DjangoTemplates` that specifies
+:attr:`~BaseRenderer.form_template_name` and
+:attr:`~BaseRenderer.formset_template_name` as ``"django/forms/div.html"`` and
+``"django/forms/formset/div.html"`` respectively.
+
+This is a transitional renderer for opt-in to the new ``<div>`` based
+templates, which are the default from Django 5.0.
+
+Apply this via the :setting:`FORM_RENDERER` setting::
+
+    FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
+
+Once the ``<div>`` templates are the default, this transitional renderer will
+be deprecated, for removal in Django 6.0. The ``FORM_RENDERER`` declaration can
+be removed at that time.
+
 ``Jinja2``
 ----------
 
@@ -113,6 +145,17 @@ templates for widgets that don't have any, you can't use this renderer. For
 example, :mod:`django.contrib.admin` doesn't include Jinja2 templates for its
 widgets due to their usage of Django template tags.
 
+.. class:: Jinja2DivFormRenderer
+
+.. versionadded:: 4.1
+
+A transitional renderer as per :class:`DjangoDivFormRenderer` above, but
+subclassing :class:`Jinja2` for use with the Jinja2 backend.
+
+Apply this via the :setting:`FORM_RENDERER` setting::
+
+    FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"
+
 ``TemplatesSetting``
 --------------------