From fde946daffbb007a7d033945677cc8e9e475d516 Mon Sep 17 00:00:00 2001
From: Carlton Gibson <carlton.gibson@noumenal.es>
Date: Tue, 3 May 2022 16:07:01 +0200
Subject: Refs #32339 -- Restructured outputting HTML form docs.

In the topic doc, promoted the Reusable form templates section.

In the reference, re-grouped and promoted the default __str__()
rendering path, and then gathered the various as_*() helpers
subsequently.

Thanks to David Smith for review.
---
 docs/topics/forms/index.txt | 139 ++++++++++++++++++++++----------------------
 1 file changed, 71 insertions(+), 68 deletions(-)

(limited to 'docs/topics/forms')

diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index e7709834c2..c8e43389a0 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -487,15 +487,83 @@ instance into the template context. So if your form is called ``form`` in the
 context, ``{{ form }}`` will render its ``<label>`` and ``<input>`` elements
 appropriately.
 
-Form rendering options
-----------------------
-
 .. admonition:: Additional form template furniture
 
     Don't forget that a form's output does *not* include the surrounding
     ``<form>`` tags, or the form's ``submit`` control. You will have to provide
     these yourself.
 
+Reusable form templates
+-----------------------
+
+The HTML output when rendering a form is itself generated via a template. You
+can control this by creating an appropriate template file and setting a custom
+:setting:`FORM_RENDERER` to use that
+:attr:`~django.forms.renderers.BaseRenderer.form_template_name` site-wide. You
+can also customize per-form by overriding the form's
+:attr:`~django.forms.Form.template_name` attribute to render the form using the
+custom template, or by passing the template name directly to
+:meth:`.Form.render`.
+
+The example below will result in ``{{ form }}`` being rendered as the output of
+the ``form_snippet.html`` template.
+
+In your templates:
+
+.. code-block:: html+django
+
+    # In your template:
+    {{ form }}
+
+    # In form_snippet.html:
+    {% for field in form %}
+        <div class="fieldWrapper">
+            {{ field.errors }}
+            {{ field.label_tag }} {{ field }}
+        </div>
+    {% endfor %}
+
+Then you can configure the :setting:`FORM_RENDERER` setting:
+
+.. code-block:: python
+    :caption: settings.py
+
+    from django.forms.renderers import TemplatesSetting
+
+    class CustomFormRenderer(TemplatesSetting):
+        form_template_name = "form_snippet.html"
+
+    FORM_RENDERER = "project.settings.CustomFormRenderer"
+
+… or for a single form::
+
+    class MyForm(forms.Form):
+        template_name = "form_snippet.html"
+        ...
+
+… or for a single render of a form instance, passing in the template name to
+the :meth:`.Form.render`. Here's an example of this being used in a view::
+
+    def index(request):
+        form = MyForm()
+        rendered_form = form.render("form_snippet.html")
+        context = {'form': rendered_form}
+        return render(request, 'index.html', context)
+
+See :ref:`ref-forms-api-outputting-html` for more details.
+
+.. versionchanged:: 4.0
+
+    Template rendering of forms was added.
+
+.. versionchanged:: 4.1
+
+    The ability to set the default ``form_template_name`` on the form renderer
+    was added.
+
+Form rendering options
+----------------------
+
 There are other output options though for the ``<label>``/``<input>`` pairs:
 
 * ``{{ form.as_table }}`` will render them as table cells wrapped in ``<tr>``
@@ -754,71 +822,6 @@ error in a hidden field is a sign of form tampering, since normal form
 interaction won't alter them. However, you could easily insert some error
 displays for those form errors, as well.
 
-Reusable form templates
------------------------
-
-If your site uses the same rendering logic for forms in multiple places, you
-can reduce duplication by saving the form's loop in a standalone template and
-setting a custom :setting:`FORM_RENDERER` to use that
-:attr:`~django.forms.renderers.BaseRenderer.form_template_name` site-wide. You
-can also customize per-form by overriding the form's
-:attr:`~django.forms.Form.template_name` attribute to render the form using the
-custom template.
-
-The below example will result in ``{{ form }}`` being rendered as the output of
-the ``form_snippet.html`` template.
-
-In your templates:
-
-.. code-block:: html+django
-
-    # In your template:
-    {{ form }}
-
-    # In form_snippet.html:
-    {% for field in form %}
-        <div class="fieldWrapper">
-            {{ field.errors }}
-            {{ field.label_tag }} {{ field }}
-        </div>
-    {% endfor %}
-
-Then you can configure the :setting:`FORM_RENDERER` setting:
-
-.. code-block:: python
-    :caption: settings.py
-
-    from django.forms.renderers import TemplatesSetting
-
-    class CustomFormRenderer(TemplatesSetting):
-        form_template_name = "form_snippet.html"
-
-    FORM_RENDERER = "project.settings.CustomFormRenderer"
-
-… or for a single form::
-
-    class MyForm(forms.Form):
-        template_name = "form_snippet.html"
-        ...
-
-… or for a single render of a form instance, passing in the template name to
-the :meth:`.Form.render()`. Here's an example of this being used in a view::
-
-    def index(request):
-        form = MyForm()
-        rendered_form = form.render("form_snippet.html")
-        context = {'form': rendered_form}
-        return render(request, 'index.html', context)
-
-.. versionchanged:: 4.0
-
-    Template rendering of forms was added.
-
-.. versionchanged:: 4.1
-
-    The ability to set the default ``form_template_name`` on the form renderer
-    was added.
-
 Further topics
 ==============
 
-- 
cgit v1.3