From 5dceb1f07807d76f163ce1929e9f1dc1b2da6289 Mon Sep 17 00:00:00 2001
From: "Elif T. Kus" <elifkus@gmail.com>
Date: Sun, 3 Jan 2016 12:56:22 +0200
Subject: [1.9.x] Fixed #26020 -- Normalized header stylings in docs.

Backport of bca9faae95db2a92e540fbd08505c134639916fe from master
---
 docs/ref/forms/api.txt        | 48 +++++++++++-----------
 docs/ref/forms/fields.txt     | 96 +++++++++++++++++++++----------------------
 docs/ref/forms/formsets.txt   |  2 +-
 docs/ref/forms/models.txt     |  4 +-
 docs/ref/forms/validation.txt | 21 +++++-----
 docs/ref/forms/widgets.txt    | 41 +++++++++---------
 6 files changed, 107 insertions(+), 105 deletions(-)

(limited to 'docs/ref/forms')

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index a8d2fa77ff..072525ff53 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -13,7 +13,7 @@ The Forms API
 .. _ref-forms-api-bound-unbound:
 
 Bound and unbound forms
------------------------
+=======================
 
 A :class:`Form` instance is either **bound** to a set of data, or **unbound**.
 
@@ -69,7 +69,7 @@ another :class:`Form` instance. There is no way to change data in a
 should consider its data immutable, whether it has data or not.
 
 Using forms to validate data
-----------------------------
+============================
 
 .. method:: Form.clean()
 
@@ -203,7 +203,7 @@ This includes ``ValidationError``\s that are raised in :meth:`Form.clean()
 "...") <django.forms.Form.add_error>`.
 
 Behavior of unbound forms
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 It's meaningless to validate a form with no data, but, for the record, here's
 what happens with unbound forms::
@@ -215,7 +215,7 @@ what happens with unbound forms::
     {}
 
 Dynamic initial values
-----------------------
+======================
 
 .. attribute:: Form.initial
 
@@ -251,7 +251,7 @@ precedence::
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
 Checking which form data has changed
-------------------------------------
+====================================
 
 .. method:: Form.has_changed()
 
@@ -288,7 +288,7 @@ provided in :attr:`~Form.initial`. It returns an empty list if no data differs.
     ...     print("The following fields changed: %s" % ", ".join(f.changed_data))
 
 Accessing the fields from the form
-----------------------------------
+==================================
 
 .. attribute:: Form.fields
 
@@ -322,7 +322,7 @@ process::
     '<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>'
 
 Accessing "clean" data
-----------------------
+======================
 
 .. attribute:: Form.cleaned_data
 
@@ -416,7 +416,7 @@ fields). More information about this is in :doc:`/ref/forms/validation`.
 .. _ref-forms-api-outputting-html:
 
 Outputting forms as HTML
-------------------------
+========================
 
 The second task of a ``Form`` object is to render itself as HTML. To do so,
 simply ``print`` it::
@@ -478,7 +478,7 @@ form, other output styles are available. Each style is available as a method on
 a form object, and each rendering method returns a Unicode object.
 
 ``as_p()``
-~~~~~~~~~~
+----------
 
 .. method:: Form.as_p()
 
@@ -495,7 +495,7 @@ containing one field::
     <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
 
 ``as_ul()``
-~~~~~~~~~~~
+-----------
 
 .. method:: Form.as_ul()
 
@@ -514,7 +514,7 @@ flexibility::
     <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>
 
 ``as_table()``
-~~~~~~~~~~~~~~
+--------------
 
 .. method:: Form.as_table()
 
@@ -534,7 +534,7 @@ it calls its ``as_table()`` method behind the scenes::
 .. _ref-forms-api-styling-form-rows:
 
 Styling required or erroneous form rows
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
 
 .. attribute:: Form.error_css_class
 .. attribute:: Form.required_css_class
@@ -578,7 +578,7 @@ classes, as needed. The HTML will look something like::
 .. _ref-forms-api-configuring-label:
 
 Configuring form elements' HTML ``id`` attributes and ``<label>`` tags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------------------------
 
 .. attribute:: Form.auto_id
 
@@ -702,7 +702,7 @@ using the ``label_suffix`` parameter to
 :meth:`~django.forms.BoundField.label_tag`.
 
 Notes on field ordering
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
 displayed in the order in which you define them in your form class. For
@@ -736,7 +736,7 @@ You may rearrange the fields any time using ``order_fields()`` with a list of
 field names as in :attr:`~django.forms.Form.field_order`.
 
 How errors are displayed
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 If you render a bound ``Form`` object, the act of rendering will automatically
 run the form's validation if it hasn't already happened, and the HTML output
@@ -770,7 +770,7 @@ method you're using::
 .. _ref-forms-error-list-format:
 
 Customizing the error list format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 By default, forms use ``django.forms.utils.ErrorList`` to format validation
 errors. If you'd like to use an alternate class for displaying errors, you can
@@ -794,7 +794,7 @@ Python 2)::
     <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
 
 More granular output
---------------------
+====================
 
 The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts --
 they're not the only way a form object can be displayed.
@@ -833,7 +833,7 @@ The field-specific output honors the form object's ``auto_id`` setting::
     <input type="text" name="message" id="id_message" />
 
 Attributes of ``BoundField``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 .. attribute:: BoundField.data
 
@@ -931,7 +931,7 @@ Attributes of ``BoundField``
         message
 
 Methods of ``BoundField``
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 .. method:: BoundField.as_hidden(attrs=None, **kwargs)
 
@@ -1008,7 +1008,7 @@ Methods of ``BoundField``
         hi
 
 Customizing ``BoundField``
---------------------------
+==========================
 
 .. versionadded:: 1.9
 
@@ -1052,7 +1052,7 @@ Now you can access the country in a template with
 .. _binding-uploaded-files:
 
 Binding uploaded files to a form
---------------------------------
+================================
 
 Dealing with forms that have ``FileField`` and ``ImageField`` fields
 is a little more complicated than a normal form.
@@ -1093,7 +1093,7 @@ form data *and* file data::
     >>> f = ContactFormWithMugshot()
 
 Testing for multipart forms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 .. method:: Form.is_multipart()
 
@@ -1116,7 +1116,7 @@ Here's an example of how you might use this in a template::
     </form>
 
 Subclassing forms
------------------
+=================
 
 If you have multiple ``Form`` classes that share fields, you can use
 subclassing to remove redundancy.
@@ -1177,7 +1177,7 @@ by setting the name of the field to ``None`` on the subclass. For example::
 .. _form-prefix:
 
 Prefixes for forms
-------------------
+==================
 
 .. attribute:: Form.prefix
 
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index bdc90f09e0..ef27f692b9 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -33,14 +33,14 @@ exception or returns the clean value::
 .. _core-field-arguments:
 
 Core field arguments
---------------------
+====================
 
 Each ``Field`` class constructor takes at least these arguments. Some
 ``Field`` classes take additional, field-specific arguments, but the following
 should *always* be accepted:
 
 ``required``
-~~~~~~~~~~~~
+------------
 
 .. attribute:: Field.required
 
@@ -93,7 +93,7 @@ For other ``Field`` classes, it might be ``None``. (This varies from field to
 field.)
 
 ``label``
-~~~~~~~~~
+---------
 
 .. attribute:: Field.label
 
@@ -120,7 +120,7 @@ We've specified ``auto_id=False`` to simplify the output::
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
 ``label_suffix``
-~~~~~~~~~~~~~~~~
+----------------
 
 .. attribute:: Field.label_suffix
 
@@ -140,7 +140,7 @@ The ``label_suffix`` argument lets you override the form's
     <p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p>
 
 ``initial``
-~~~~~~~~~~~
+-----------
 
 .. attribute:: Field.initial
 
@@ -208,7 +208,7 @@ Instead of a constant, you can also pass any callable::
 The callable will be evaluated only when the unbound form is displayed, not when it is defined.
 
 ``widget``
-~~~~~~~~~~
+----------
 
 .. attribute:: Field.widget
 
@@ -216,7 +216,7 @@ The ``widget`` argument lets you specify a ``Widget`` class to use when
 rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information.
 
 ``help_text``
-~~~~~~~~~~~~~
+-------------
 
 .. attribute:: Field.help_text
 
@@ -255,7 +255,7 @@ fields. We've specified ``auto_id=False`` to simplify the output::
     <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
 
 ``error_messages``
-~~~~~~~~~~~~~~~~~~
+------------------
 
 .. attribute:: Field.error_messages
 
@@ -282,7 +282,7 @@ In the `built-in Field classes`_ section below, each ``Field`` defines the
 error message keys it uses.
 
 ``validators``
-~~~~~~~~~~~~~~
+--------------
 
 .. attribute:: Field.validators
 
@@ -292,18 +292,18 @@ for this field.
 See the :doc:`validators documentation </ref/validators>` for more information.
 
 ``localize``
-~~~~~~~~~~~~
+------------
 
 .. attribute:: Field.localize
 
 The ``localize`` argument enables the localization of form data input, as well
 as the rendered output.
 
-See the :ref:`format localization <format-localization>` documentation for
+See the :doc:`format localization </topics/i18n/formatting>` documentation for
 more information.
 
 ``disabled``
-~~~~~~~~~~~~
+------------
 
 .. attribute:: Field.disabled
 
@@ -315,10 +315,10 @@ Even if a user tampers with the field's value submitted to the server, it will
 be ignored in favor of the value from the form's initial data.
 
 Checking if the field data has changed
---------------------------------------
+======================================
 
 ``has_changed()``
-~~~~~~~~~~~~~~~~~~
+-----------------
 
 .. method:: Field.has_changed()
 
@@ -334,7 +334,7 @@ See the :class:`Form.has_changed()` documentation for more information.
 .. _built-in-fields:
 
 Built-in ``Field`` classes
---------------------------
+==========================
 
 Naturally, the ``forms`` library comes with a set of ``Field`` classes that
 represent common validation needs. This section documents each built-in field.
@@ -344,7 +344,7 @@ For each field, we describe the default widget used if you don't specify
 (see the section on ``required`` above to understand what that means).
 
 ``BooleanField``
-~~~~~~~~~~~~~~~~
+----------------
 
 .. class:: BooleanField(**kwargs)
 
@@ -364,7 +364,7 @@ For each field, we describe the default widget used if you don't specify
         creating the ``BooleanField``.
 
 ``CharField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: CharField(**kwargs)
 
@@ -391,7 +391,7 @@ For each field, we describe the default widget used if you don't specify
        trailing whitespace.
 
 ``ChoiceField``
-~~~~~~~~~~~~~~~
+---------------
 
 .. class:: ChoiceField(**kwargs)
 
@@ -420,7 +420,7 @@ For each field, we describe the default widget used if you don't specify
             The ability to pass a callable to ``choices`` was added.
 
 ``TypedChoiceField``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. class:: TypedChoiceField(**kwargs)
 
@@ -452,7 +452,7 @@ For each field, we describe the default widget used if you don't specify
         accordingly.
 
 ``DateField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: DateField(**kwargs)
 
@@ -488,10 +488,10 @@ For each field, we describe the default widget used if you don't specify
          '%d %B %Y',      # '25 October 2006'
          '%d %B, %Y']     # '25 October, 2006'
 
-    See also :ref:`format localization <format-localization>`.
+    See also :doc:`format localization </topics/i18n/formatting>`.
 
 ``DateTimeField``
-~~~~~~~~~~~~~~~~~
+-----------------
 
 .. class:: DateTimeField(**kwargs)
 
@@ -521,10 +521,10 @@ For each field, we describe the default widget used if you don't specify
          '%m/%d/%y %H:%M',       # '10/25/06 14:30'
          '%m/%d/%y']             # '10/25/06'
 
-    See also :ref:`format localization <format-localization>`.
+    See also :doc:`format localization </topics/i18n/formatting>`.
 
 ``DecimalField``
-~~~~~~~~~~~~~~~~
+----------------
 
 .. class:: DecimalField(**kwargs)
 
@@ -562,7 +562,7 @@ For each field, we describe the default widget used if you don't specify
         The maximum number of decimal places permitted.
 
 ``DurationField``
-~~~~~~~~~~~~~~~~~
+-----------------
 
 .. versionadded:: 1.8
 
@@ -579,7 +579,7 @@ For each field, we describe the default widget used if you don't specify
     :func:`~django.utils.dateparse.parse_duration`.
 
 ``EmailField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: EmailField(**kwargs)
 
@@ -595,7 +595,7 @@ For each field, we describe the default widget used if you don't specify
     given length.
 
 ``FileField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: FileField(**kwargs)
 
@@ -623,7 +623,7 @@ For each field, we describe the default widget used if you don't specify
     length and ``%(length)d`` will be replaced with the current filename length.
 
 ``FilePathField``
-~~~~~~~~~~~~~~~~~
+-----------------
 
 .. class:: FilePathField(**kwargs)
 
@@ -666,7 +666,7 @@ For each field, we describe the default widget used if you don't specify
 
 
 ``FloatField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: FloatField(**kwargs)
 
@@ -683,7 +683,7 @@ For each field, we describe the default widget used if you don't specify
     These control the range of values permitted in the field.
 
 ``ImageField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: ImageField(**kwargs)
 
@@ -720,7 +720,7 @@ For each field, we describe the default widget used if you don't specify
 .. _Image: https://pillow.readthedocs.org/en/latest/reference/Image.html
 
 ``IntegerField``
-~~~~~~~~~~~~~~~~
+----------------
 
 .. class:: IntegerField(**kwargs)
 
@@ -744,7 +744,7 @@ For each field, we describe the default widget used if you don't specify
     These control the range of values permitted in the field.
 
 ``GenericIPAddressField``
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 .. class:: GenericIPAddressField(**kwargs)
 
@@ -779,7 +779,7 @@ For each field, we describe the default widget used if you don't specify
         when ``protocol`` is set to ``'both'``.
 
 ``MultipleChoiceField``
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 .. class:: MultipleChoiceField(**kwargs)
 
@@ -796,7 +796,7 @@ For each field, we describe the default widget used if you don't specify
     Takes one extra required argument, ``choices``, as for :class:`ChoiceField`.
 
 ``TypedMultipleChoiceField``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 .. class:: TypedMultipleChoiceField(**kwargs)
 
@@ -818,7 +818,7 @@ For each field, we describe the default widget used if you don't specify
     :class:`TypedChoiceField`.
 
 ``NullBooleanField``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. class:: NullBooleanField(**kwargs)
 
@@ -828,7 +828,7 @@ For each field, we describe the default widget used if you don't specify
     * Validates nothing (i.e., it never raises a ``ValidationError``).
 
 ``RegexField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: RegexField(**kwargs)
 
@@ -865,7 +865,7 @@ For each field, we describe the default widget used if you don't specify
         message as the value.
 
 ``SlugField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: SlugField(**kwargs)
 
@@ -889,7 +889,7 @@ For each field, we describe the default widget used if you don't specify
        to ASCII letters. Defaults to ``False``.
 
 ``TimeField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: TimeField(**kwargs)
 
@@ -913,7 +913,7 @@ For each field, we describe the default widget used if you don't specify
         '%H:%M',        # '14:30'
 
 ``URLField``
-~~~~~~~~~~~~
+------------
 
 .. class:: URLField(**kwargs)
 
@@ -931,7 +931,7 @@ For each field, we describe the default widget used if you don't specify
     These are the same as ``CharField.max_length`` and ``CharField.min_length``.
 
 ``UUIDField``
-~~~~~~~~~~~~~
+-------------
 
 .. versionadded:: 1.8
 
@@ -946,10 +946,10 @@ For each field, we describe the default widget used if you don't specify
     to the :class:`~python:uuid.UUID` constructor.
 
 Slightly complex built-in ``Field`` classes
--------------------------------------------
+===========================================
 
 ``ComboField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: ComboField(**kwargs)
 
@@ -977,7 +977,7 @@ Slightly complex built-in ``Field`` classes
             ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
 
 ``MultiValueField``
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. class:: MultiValueField(fields=(), **kwargs)
 
@@ -1060,7 +1060,7 @@ Slightly complex built-in ``Field`` classes
         This method must be implemented in the subclasses.
 
 ``SplitDateTimeField``
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 .. class:: SplitDateTimeField(**kwargs)
 
@@ -1091,7 +1091,7 @@ Slightly complex built-in ``Field`` classes
     for :class:`TimeField` are used.
 
 Fields which handle relationships
----------------------------------
+=================================
 
 Two fields are available for representing relationships between
 models: :class:`ModelChoiceField` and
@@ -1114,7 +1114,7 @@ method::
             self.fields['foo_select'].queryset = ...
 
 ``ModelChoiceField``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. class:: ModelChoiceField(**kwargs)
 
@@ -1207,7 +1207,7 @@ method::
                 return "My Object #%i" % obj.id
 
 ``ModelMultipleChoiceField``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 .. class:: ModelMultipleChoiceField(**kwargs)
 
@@ -1235,7 +1235,7 @@ method::
         user's selection.
 
 Creating custom fields
-----------------------
+======================
 
 If the built-in ``Field`` classes don't meet your needs, you can easily create
 custom ``Field`` classes. To do this, just create a subclass of
diff --git a/docs/ref/forms/formsets.txt b/docs/ref/forms/formsets.txt
index 704a9bb198..144140c62e 100644
--- a/docs/ref/forms/formsets.txt
+++ b/docs/ref/forms/formsets.txt
@@ -12,4 +12,4 @@ Formset API reference. For introductory material about formsets, see the
 
     Returns a ``FormSet`` class for the given ``form`` class.
 
-    See :ref:`formsets` for example usage.
+    See :doc:`formsets </topics/forms/formsets>` for example usage.
diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt
index bdf6ba1d89..f39d238aa7 100644
--- a/docs/ref/forms/models.txt
+++ b/docs/ref/forms/models.txt
@@ -66,8 +66,8 @@ Model Form API reference. For introductory material about model forms, see the
 
     Arguments ``formset``, ``extra``, ``max_num``, ``can_order``,
     ``can_delete`` and ``validate_max`` are passed through to
-    :func:`~django.forms.formsets.formset_factory`. See :ref:`formsets` for
-    details.
+    :func:`~django.forms.formsets.formset_factory`. See :doc:`formsets
+    </topics/forms/formsets>` for details.
 
     See :ref:`model-formsets` for example usage.
 
diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt
index 7f334f4361..bb9a928c1a 100644
--- a/docs/ref/forms/validation.txt
+++ b/docs/ref/forms/validation.txt
@@ -1,10 +1,9 @@
-.. currentmodule:: django.forms
-
-.. _form-and-field-validation:
-
+=========================
 Form and field validation
 =========================
 
+.. currentmodule:: django.forms
+
 Form validation happens when the data is cleaned. If you want to customize
 this process, there are various places to make changes, each one serving a
 different purpose. Three types of cleaning methods are run during form
@@ -112,7 +111,7 @@ for all remaining fields are still executed.
 .. _raising-validation-error:
 
 Raising ``ValidationError``
----------------------------
+===========================
 
 In order to make error messages flexible and easy to override, consider the
 following guidelines:
@@ -184,7 +183,7 @@ greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name
 and a ``params`` dictionary).
 
 Raising multiple errors
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 If you detect multiple errors during a cleaning method and wish to signal all
 of them to the form submitter, it is possible to pass a list of errors to the
@@ -206,7 +205,7 @@ with ``code``\s and ``params`` but a list of strings will also work::
     ])
 
 Using validation in practice
-----------------------------
+============================
 
 The previous sections explained how validation works in general for forms.
 Since it can sometimes be easier to put things into place by seeing each
@@ -216,7 +215,7 @@ previous features.
 .. _validators:
 
 Using validators
-~~~~~~~~~~~~~~~~
+----------------
 
 Django's form (and model) fields support use of simple utility functions and
 classes known as validators. A validator is merely a callable object or
@@ -254,7 +253,7 @@ argument being the pattern: ``^[-a-zA-Z0-9_]+$``. See the section on
 available and for an example of how to write a validator.
 
 Form field default cleaning
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 Let's first create a custom form field that validates its input is a string
 containing comma-separated email addresses. The full class looks like this::
@@ -300,7 +299,7 @@ method will be run as part of the cleaning process and it will, in turn, call
 the custom ``to_python()`` and ``validate()`` methods.
 
 Cleaning a specific field attribute
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 Continuing on from the previous example, suppose that in our ``ContactForm``,
 we want to make sure that the ``recipients`` field always contains the address
@@ -326,7 +325,7 @@ write a cleaning method that operates on the ``recipients`` field, like so::
 .. _validating-fields-with-clean:
 
 Cleaning and validating fields that depend on each other
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------
 
 Suppose we add another requirement to our contact form: if the ``cc_myself``
 field is ``True``, the ``subject`` must contain the word ``"help"``. We are
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 5e51ec10b1..f5ca010d63 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -22,7 +22,7 @@ dictionary that corresponds to the widget.
 .. _widget-to-field:
 
 Specifying widgets
-------------------
+==================
 
 Whenever you specify a field on a form, Django will use a default widget
 that is appropriate to the type of data that is to be displayed. To find
@@ -43,9 +43,8 @@ example::
 This would specify a form with a comment that uses a larger :class:`Textarea`
 widget, rather than the default :class:`TextInput` widget.
 
-
 Setting arguments for widgets
------------------------------
+=============================
 
 Many widgets have optional extra arguments; they can be set when defining the
 widget on the field. In the following example, the
@@ -69,9 +68,8 @@ widget on the field. In the following example, the
 See the :ref:`built-in widgets` for more information about which widgets
 are available and which arguments they accept.
 
-
 Widgets inheriting from the Select widget
------------------------------------------
+=========================================
 
 Widgets inheriting from the :class:`Select` widget deal with choices. They
 present the user with a list of options to choose from. The different widgets
@@ -96,14 +94,13 @@ example::
     >>> choice_field.widget.choices
     [('1', 'First and only')]
 
-
 Widgets which offer a :attr:`~Select.choices` attribute can however be used
 with fields which are not based on choice -- such as a :class:`CharField` --
 but it is recommended to use a :class:`ChoiceField`-based field when the
 choices are inherent to the model and not just the representational widget.
 
 Customizing widget instances
-----------------------------
+============================
 
 When Django renders a widget as HTML, it only renders very minimal markup -
 Django doesn't add class names, or any other widget-specific attributes. This
@@ -116,7 +113,7 @@ There are two ways to customize widgets: :ref:`per widget instance
 .. _styling-widget-instances:
 
 Styling widget instances
-^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------
 
 If you want to make one widget instance look different from another, you will
 need to specify additional attributes at the time when the widget object is
@@ -167,7 +164,7 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
 .. _styling-widget-classes:
 
 Styling widget classes
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 With widgets, it is possible to add assets (``css`` and ``javascript``)
 and more deeply customize their appearance and behavior.
@@ -181,13 +178,16 @@ detail in the :doc:`Form Assets </topics/forms/media>` topic guide.
 
 .. _base-widget-classes:
 
-Base Widget classes
--------------------
+Base widget classes
+===================
 
 Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by
 all the :ref:`built-in widgets <built-in widgets>` and may serve as a
 foundation for custom widgets.
 
+``Widget``
+----------
+
 .. class:: Widget(attrs=None)
 
     This abstract class cannot be rendered, but provides the basic attribute
@@ -259,6 +259,9 @@ foundation for custom widgets.
         customize it and add expensive processing, you should implement some
         caching mechanism yourself.
 
+``MultiWidget``
+---------------
+
 .. class:: MultiWidget(widgets, attrs=None)
 
     A widget that is composed of multiple widgets.
@@ -412,7 +415,7 @@ foundation for custom widgets.
 .. _built-in widgets:
 
 Built-in widgets
-----------------
+================
 
 Django provides a representation of all the basic HTML widgets, plus some
 commonly used groups of widgets in the ``django.forms.widgets`` module,
@@ -423,7 +426,7 @@ and :ref:`handling of multi-valued input <composite-widgets>`.
 .. _text-widgets:
 
 Widgets handling input of text
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
 
 These widgets make use of the HTML elements ``input`` and ``textarea``.
 
@@ -498,7 +501,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
 
     If no ``format`` argument is provided, the default format is the first
     format found in :setting:`DATE_INPUT_FORMATS` and respects
-    :ref:`format-localization`.
+    :doc:`/topics/i18n/formatting`.
 
 ``DateTimeInput``
 ~~~~~~~~~~~~~~~~~
@@ -515,7 +518,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
 
     If no ``format`` argument is provided, the default format is the first
     format found in :setting:`DATETIME_INPUT_FORMATS` and respects
-    :ref:`format-localization`.
+    :doc:`/topics/i18n/formatting`.
 
     By default, the microseconds part of the time value is always set to ``0``.
     If microseconds are required, use a subclass with the
@@ -536,7 +539,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
 
     If no ``format`` argument is provided, the default format is the first
     format found in :setting:`TIME_INPUT_FORMATS` and respects
-    :ref:`format-localization`.
+    :doc:`/topics/i18n/formatting`.
 
     For the treatment of microseconds, see :class:`DateTimeInput`.
 
@@ -550,7 +553,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
 .. _selector-widgets:
 
 Selector and checkbox widgets
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
 ``CheckboxInput``
 ~~~~~~~~~~~~~~~~~
@@ -714,7 +717,7 @@ When looping over the checkboxes, the ``label`` and ``input`` tags include
 .. _file-upload-widgets:
 
 File upload widgets
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 ``FileInput``
 ~~~~~~~~~~~~~
@@ -735,7 +738,7 @@ File upload widgets
 .. _composite-widgets:
 
 Composite widgets
-^^^^^^^^^^^^^^^^^
+-----------------
 
 ``MultipleHiddenInput``
 ~~~~~~~~~~~~~~~~~~~~~~~
-- 
cgit v1.3