Fixed #26020 -- Normalized header stylings in docs.

22 files changed, 136 insertions, 138 deletions

diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt
index a4bb3a190a..0c3ac0b742 100644
--- a/docs/topics/class-based-views/generic-display.txt
+++ b/docs/topics/class-based-views/generic-display.txt
@@ -1,5 +1,3 @@
-.. _Generic views:
-
 ==================================
 Built-in class-based generic views
 ==================================
diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt
index f5fa2ffcdb..0a1cd06961 100644
--- a/docs/topics/class-based-views/generic-editing.txt
+++ b/docs/topics/class-based-views/generic-editing.txt
@@ -1,3 +1,4 @@
+====================================
 Form handling with class-based views
 ====================================
 
@@ -13,7 +14,7 @@ this, Django provides a collection of generic class-based views for form
 processing.
 
 Basic Forms
------------
+===========
 
 Given a simple contact form:
 
@@ -60,7 +61,7 @@ Notes:
   redirects to the :attr:`~django.views.generic.edit.FormMixin.success_url`.
 
 Model Forms
------------
+===========
 
 Generic views really shine when working with models.  These generic
 views will automatically create a :class:`~django.forms.ModelForm`, so long as
@@ -180,7 +181,7 @@ Finally, we hook these new views into the URLconf:
     on your view class.
 
 Models and request.user
------------------------
+=======================
 
 To track the user that created an object using a :class:`CreateView`,
 you can use a custom :class:`~django.forms.ModelForm` to do this. First, add
@@ -223,7 +224,7 @@ alternatively handle unauthorized users in the
 :meth:`~django.views.generic.edit.ModelFormMixin.form_valid()`.
 
 AJAX example
-------------
+============
 
 Here is a simple example showing how you might go about implementing a form that
 works for AJAX requests as well as 'normal' form POSTs::
diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt
index 4966ff9272..13c2b96c8f 100644
--- a/docs/topics/db/examples/many_to_many.txt
+++ b/docs/topics/db/examples/many_to_many.txt
@@ -1,6 +1,6 @@
-##########################
+==========================
 Many-to-many relationships
-##########################
+==========================
 
 .. highlight:: pycon
 
diff --git a/docs/topics/db/examples/many_to_one.txt b/docs/topics/db/examples/many_to_one.txt
index 64f6ab1f1b..c57d996460 100644
--- a/docs/topics/db/examples/many_to_one.txt
+++ b/docs/topics/db/examples/many_to_one.txt
@@ -1,6 +1,6 @@
-#########################
+=========================
 Many-to-one relationships
-#########################
+=========================
 
 To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`::
 
diff --git a/docs/topics/db/examples/one_to_one.txt b/docs/topics/db/examples/one_to_one.txt
index 7e373a98e1..c3060d86bb 100644
--- a/docs/topics/db/examples/one_to_one.txt
+++ b/docs/topics/db/examples/one_to_one.txt
@@ -1,6 +1,6 @@
-########################
+========================
 One-to-one relationships
-########################
+========================
 
 To define a one-to-one relationship, use :ref:`ref-onetoone`.
 
diff --git a/docs/topics/db/index.txt b/docs/topics/db/index.txt
index 5b45e36e7c..79624d7fdf 100644
--- a/docs/topics/db/index.txt
+++ b/docs/topics/db/index.txt
@@ -1,3 +1,4 @@
+====================
 Models and databases
 ====================
 
diff --git a/docs/topics/db/tablespaces.txt b/docs/topics/db/tablespaces.txt
index 8c60fd568e..6cda629254 100644
--- a/docs/topics/db/tablespaces.txt
+++ b/docs/topics/db/tablespaces.txt
@@ -14,7 +14,7 @@ A common paradigm for optimizing performance in database systems is the use of
 
 
 Declaring tablespaces for tables
---------------------------------
+================================
 
 A tablespace can be specified for the table generated by a model by supplying
 the :attr:`~django.db.models.Options.db_tablespace` option inside the model's
@@ -27,7 +27,7 @@ a tablespace for the built-in Django apps and other applications whose code you
 cannot control.
 
 Declaring tablespaces for indexes
----------------------------------
+=================================
 
 You can pass the :attr:`~django.db.models.Field.db_tablespace` option to a
 ``Field`` constructor to specify an alternate tablespace for the ``Field``’s
@@ -42,7 +42,7 @@ set :setting:`DEFAULT_INDEX_TABLESPACE`, the index is created in the same
 tablespace as the tables.
 
 An example
-----------
+==========
 
 .. code-block:: python
 
@@ -62,7 +62,7 @@ also generate an index, but no tablespace for it is specified, so it would be
 stored in the model tablespace ``tables`` by default.
 
 Database support
-----------------
+================
 
 PostgreSQL and Oracle support tablespaces. SQLite and MySQL don't.
 
diff --git a/docs/topics/external-packages.txt b/docs/topics/external-packages.txt
index 29a6c3dc41..e74274c0fd 100644
--- a/docs/topics/external-packages.txt
+++ b/docs/topics/external-packages.txt
@@ -7,7 +7,7 @@ problems (``contrib.*``). For easier maintenance and to trim the size of the
 codebase, a few of those applications have been moved out to separate projects.
 
 Localflavor
-~~~~~~~~~~~
+===========
 
 ``django-localflavor`` is a collection of utilities for particular countries
 and cultures.
@@ -17,7 +17,7 @@ and cultures.
 * `PyPI <https://pypi.python.org/pypi/django-localflavor>`__
 
 Comments
-~~~~~~~~
+========
 
 ``django-contrib-comments`` can be used to attach comments to any model, so you
 can use it for comments on blog entries, photos, book chapters, or anything
@@ -29,7 +29,7 @@ product like Disqus.
 * `PyPI <https://pypi.python.org/pypi/django-contrib-comments>`__
 
 Formtools
-~~~~~~~~~
+=========
 
 ``django-formtools`` is a collection of assorted utilities to work with forms.
 
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt
index 5620693582..1871c223ac 100644
--- a/docs/topics/forms/formsets.txt
+++ b/docs/topics/forms/formsets.txt
@@ -1,5 +1,4 @@
-.. _formsets:
-
+========
 Formsets
 ========
 
@@ -51,7 +50,7 @@ matching behavior.
 .. _formsets-initial-data:
 
 Using initial data with a formset
----------------------------------
+=================================
 
 Initial data is what drives the main usability of a formset. As shown above
 you can define the number of extra forms. What this means is that you are
@@ -88,7 +87,7 @@ list of dictionaries as the initial data.
 .. _formsets-max-num:
 
 Limiting the maximum number of forms
-------------------------------------
+====================================
 
 The ``max_num`` parameter to :func:`~django.forms.formsets.formset_factory`
 gives you the ability to limit the number of forms the formset will display::
@@ -124,7 +123,7 @@ affect validation.  If ``validate_max=True`` is passed to the
 validation.  See :ref:`validate_max`.
 
 Formset validation
-------------------
+==================
 
 Validation with a formset is almost identical to a regular ``Form``. There is
 an ``is_valid`` method on the formset to provide a convenient way to validate
@@ -195,7 +194,7 @@ sent without any data)::
 .. _understanding-the-managementform:
 
 Understanding the ManagementForm
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 You may have noticed the additional data (``form-TOTAL_FORMS``,
 ``form-INITIAL_FORMS`` and ``form-MAX_NUM_FORMS``) that was required
@@ -227,7 +226,7 @@ the management data by rendering ``{{ my_formset.management_form }}``
 (substituting the name of your formset as appropriate).
 
 ``total_form_count`` and ``initial_form_count``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 ``BaseFormSet`` has a couple of methods that are closely related to the
 ``ManagementForm``, ``total_form_count`` and ``initial_form_count``.
@@ -241,14 +240,14 @@ sure you understand what they do before doing so.
 .. _empty_form:
 
 ``empty_form``
-~~~~~~~~~~~~~~
+--------------
 
 ``BaseFormSet`` provides an additional attribute ``empty_form`` which returns
 a form instance with a prefix of ``__prefix__`` for easier use in dynamic
 forms with JavaScript.
 
 Custom formset validation
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 A formset has a ``clean`` method similar to the one on a ``Form`` class. This
 is where you define your own validation that works at the formset level::
@@ -295,14 +294,14 @@ method on the formset.
 .. _validate_max:
 
 Validating the number of forms in a formset
--------------------------------------------
+===========================================
 
 Django provides a couple ways to validate the minimum or maximum number of
 submitted forms. Applications which need more customizable validation of the
 number of forms should use custom formset validation.
 
 ``validate_max``
-~~~~~~~~~~~~~~~~
+----------------
 
 If ``validate_max=True`` is passed to
 :func:`~django.forms.formsets.formset_factory`, validation will also check
@@ -344,7 +343,7 @@ excessive.
     using forged POST requests.
 
 ``validate_min``
-~~~~~~~~~~~~~~~~
+----------------
 
 If ``validate_min=True`` is passed to
 :func:`~django.forms.formsets.formset_factory`, validation will also check
@@ -373,14 +372,14 @@ deletion, is greater than or equal to ``min_num``.
     ['Please submit 3 or more forms.']
 
 Dealing with ordering and deletion of forms
--------------------------------------------
+===========================================
 
 The :func:`~django.forms.formsets.formset_factory` provides two optional
 parameters ``can_order`` and ``can_delete`` to help with ordering of forms in
 formsets and deletion of forms from a formset.
 
 ``can_order``
-~~~~~~~~~~~~~
+-------------
 
 .. attribute:: BaseFormSet.can_order
 
@@ -440,7 +439,7 @@ happen when the user changes these values::
     {'pub_date': datetime.date(2008, 5, 10), 'ORDER': 2, 'title': 'Article #1'}
 
 ``can_delete``
-~~~~~~~~~~~~~~
+--------------
 
 .. attribute:: BaseFormSet.can_delete
 
@@ -512,7 +511,7 @@ handle ``formset.deleted_forms``, perhaps in your formset's ``save()`` method,
 as there's no general notion of what it means to delete a form.
 
 Adding additional fields to a formset
--------------------------------------
+=====================================
 
 If you need to add additional fields to the formset this can be easily
 accomplished. The formset base class provides an ``add_fields`` method. You
@@ -538,7 +537,7 @@ default fields/attributes of the order and deletion fields::
 .. _custom-formset-form-kwargs:
 
 Passing custom parameters to formset forms
-------------------------------------------
+==========================================
 
 Sometimes your form class takes custom parameters, like ``MyArticleForm``.
 You can pass this parameter when instantiating the formset::
@@ -575,7 +574,7 @@ argument - the index of the form in the formset. The index is ``None`` for the
     The ``form_kwargs`` argument was added.
 
 Using a formset in views and templates
---------------------------------------
+======================================
 
 Using a formset inside a view is as easy as using a regular ``Form`` class.
 The only thing you will want to be aware of is making sure to use the
@@ -625,7 +624,7 @@ The above ends up calling the ``as_table`` method on the formset class.
 .. _manually-rendered-can-delete-and-can-order:
 
 Manually rendered ``can_delete`` and ``can_order``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------
 
 If you manually render fields in the template, you can render
 ``can_delete`` parameter with ``{{ form.DELETE }}``:
@@ -650,7 +649,7 @@ Similarly, if the formset has the ability to order (``can_order=True``), it is
 possible to render it with ``{{ form.ORDER }}``.
 
 Using more than one formset in a view
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 You are able to use more than one formset in a view if you like. Formsets
 borrow much of its behavior from forms. With that said you are able to use
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index 412ee1493e..4fea549bf7 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -221,7 +221,7 @@ Building a form in Django
 -------------------------
 
 The :class:`Form` class
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 
 We already know what we want our HTML form to look like. Our starting point for
 it in Django is this:
@@ -267,7 +267,7 @@ We'll have to provide those ourselves in the template.
 .. _using-a-form-in-a-view:
 
 The view
-^^^^^^^^
+~~~~~~~~
 
 Form data sent back to a Django website is processed by a view, generally the
 same view which published the form. This allows us to reuse some of the same
@@ -324,7 +324,7 @@ telling it where to go next.
 .. _topics-forms-index-basic-form-template:
 
 The template
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 We don't need to do much in our ``name.html`` template. The simplest example
 is:
@@ -420,7 +420,7 @@ this case, our form has four fields: ``subject``, ``message``, ``sender`` and
 can be found in :doc:`/ref/forms/fields`.
 
 Widgets
-^^^^^^^
+~~~~~~~
 
 Each form field has a corresponding :doc:`Widget class </ref/forms/widgets/>`,
 which in turn corresponds to an HTML form widget such as ``<input
@@ -433,7 +433,7 @@ instead, you'd specify the appropriate widget when defining your form field,
 as we have done for the ``message`` field.
 
 Field data
-^^^^^^^^^^
+~~~~~~~~~~
 
 Whatever the data submitted with a form, once it has been successfully
 validated by calling ``is_valid()`` (and ``is_valid()`` has returned ``True``),
@@ -573,7 +573,7 @@ Complete ``<label>`` elements can also be generated using the
 
 
 Rendering form error messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Of course, the price of this flexibility is more work. Until now we haven't had
 to worry about how to display form errors, because that's taken care of for us.
@@ -695,7 +695,7 @@ Useful attributes on ``{{ field }}`` include:
     :class:`~django.forms.BoundField`.
 
 Looping over hidden and visible fields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you're manually laying out a form in a template, as opposed to relying on
 Django's default form layout, you might want to treat ``<input type="hidden">``
diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt
index 180cd92995..1e2345ba20 100644
--- a/docs/topics/forms/media.txt
+++ b/docs/topics/forms/media.txt
@@ -1,3 +1,4 @@
+=================================
 Form Assets (the ``Media`` class)
 =================================
 
@@ -42,7 +43,7 @@ in a form suitable for easy inclusion on your Web page.
 .. _assets-as-a-static-definition:
 
 Assets as a static definition
------------------------------
+=============================
 
 The easiest way to define assets is as a static definition. Using this
 method, the declaration is an inner ``Media`` class. The properties of the
@@ -77,7 +78,7 @@ can be retrieved through this property::
 Here's a list of all possible ``Media`` options. There are no required options.
 
 ``css``
-~~~~~~~
+-------
 
 A dictionary describing the CSS files required for various forms of output
 media.
@@ -118,14 +119,14 @@ If this last CSS definition were to be rendered, it would become the following H
     <link href="http://static.example.com/newspaper.css" type="text/css" media="print" rel="stylesheet" />
 
 ``js``
-~~~~~~
+------
 
 A tuple describing the required JavaScript files. See :ref:`the
 section on paths <form-asset-paths>` for details of how to specify
 paths to these files.
 
 ``extend``
-~~~~~~~~~~
+----------
 
 A boolean defining inheritance behavior for ``Media`` declarations.
 
@@ -174,7 +175,7 @@ complete control over which files are inherited, and which are not.
 .. _dynamic-property:
 
 ``Media`` as a dynamic property
--------------------------------
+===============================
 
 If you need to perform some more sophisticated manipulation of asset
 requirements, you can define the ``media`` property directly. This is
@@ -198,7 +199,7 @@ return values for dynamic ``media`` properties.
 .. _form-asset-paths:
 
 Paths in asset definitions
---------------------------
+==========================
 
 Paths used to specify assets can be either relative or absolute. If a
 path starts with ``/``, ``http://`` or ``https://``, it will be
@@ -253,7 +254,7 @@ Or if :mod:`~django.contrib.staticfiles` is configured using the
     Older versions didn't serve assets using :mod:`django.contrib.staticfiles`.
 
 ``Media`` objects
------------------
+=================
 
 When you interrogate the ``media`` attribute of a widget or form, the
 value that is returned is a ``forms.Media`` object. As we have already
@@ -264,7 +265,7 @@ HTML page.
 However, ``Media`` objects have some other interesting properties.
 
 Subsets of assets
-~~~~~~~~~~~~~~~~~
+-----------------
 
 If you only want files of a particular type, you can use the subscript
 operator to filter out a medium of interest. For example::
@@ -282,7 +283,7 @@ When you use the subscript operator, the value that is returned is a
 new ``Media`` object -- but one that only contains the media of interest.
 
 Combining ``Media`` objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 ``Media`` objects can also be added together. When two ``Media`` objects are
 added, the resulting ``Media`` object contains the union of the assets
@@ -309,7 +310,7 @@ specified by both::
     <script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
 
 ``Media`` on Forms
-------------------
+==================
 
 Widgets aren't the only objects that can have ``media`` definitions --
 forms can also define ``media``. The rules for ``media`` definitions
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index 5bbb35dcb0..f3ad3cc1b1 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -210,7 +210,7 @@ Validation on a ``ModelForm``
 
 There are two main steps involved in validating a ``ModelForm``:
 
-1. :ref:`Validating the form <form-and-field-validation>`
+1. :doc:`Validating the form </ref/forms/validation>`
 2. :ref:`Validating the model instance <validating-objects>`
 
 Just like normal form validation, model form validation is triggered implicitly
@@ -234,7 +234,7 @@ validation step, right after the form's ``clean()`` method is called.
 .. _overriding-modelform-clean-method:
 
 Overriding the clean() method
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can override the ``clean()`` method on a model form to provide additional
 validation in the same way you can on a normal form.
@@ -253,7 +253,7 @@ attribute that gives its methods access to that specific model instance.
     validation, you must call the parent class's ``clean()`` method.
 
 Interaction with model validation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As part of the validation process, ``ModelForm`` will call the ``clean()``
 method of each field on your model that has a corresponding field on your form.
@@ -268,7 +268,7 @@ on the model's ``clean()`` hook.
 .. _considerations-regarding-model-errormessages:
 
 Considerations regarding model's ``error_messages``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Error messages defined at the
 :attr:`form field <django.forms.Field.error_messages>` level or at the
diff --git a/docs/topics/http/index.txt b/docs/topics/http/index.txt
index 3c53b2ea4d..a606f01b73 100644
--- a/docs/topics/http/index.txt
+++ b/docs/topics/http/index.txt
@@ -1,3 +1,4 @@
+======================
 Handling HTTP requests
 ======================
 
diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index 9d58d1829a..b16467c91a 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -330,7 +330,7 @@ cookie-stored data to prevent tampering, a :setting:`SECRET_KEY` leak
 immediately escalates to a remote code execution vulnerability.
 
 Bundled Serializers
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 .. class:: serializers.JSONSerializer
 
@@ -360,7 +360,7 @@ Bundled Serializers
 .. _custom-serializers:
 
 Write Your Own Serializer
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Note that unlike :class:`~django.contrib.sessions.serializers.PickleSerializer`,
 the :class:`~django.contrib.sessions.serializers.JSONSerializer` cannot handle
diff --git a/docs/topics/i18n/formatting.txt b/docs/topics/i18n/formatting.txt
index 1b7647d1d6..a9f5da66d7 100644
--- a/docs/topics/i18n/formatting.txt
+++ b/docs/topics/i18n/formatting.txt
@@ -1,5 +1,3 @@
-.. _format-localization:
-
 ===================
 Format localization
 ===================
diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt
index b964ccadbf..2adfd48267 100644
--- a/docs/topics/i18n/timezones.txt
+++ b/docs/topics/i18n/timezones.txt
@@ -1,5 +1,3 @@
-.. _time-zones:
-
 ==========
 Time zones
 ==========
diff --git a/docs/topics/index.txt b/docs/topics/index.txt
index 5521cd1c0e..6f85baddb6 100644
--- a/docs/topics/index.txt
+++ b/docs/topics/index.txt
@@ -1,3 +1,4 @@
+============
 Using Django
 ============
 
diff --git a/docs/topics/install.txt b/docs/topics/install.txt
index e911494ceb..f0fbc47881 100644
--- a/docs/topics/install.txt
+++ b/docs/topics/install.txt
@@ -158,7 +158,7 @@ It's easy, no matter which way you choose.
 .. _installing-official-release:
 
 Installing an official release with ``pip``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 This is the recommended way to install Django.
 
@@ -183,7 +183,7 @@ This is the recommended way to install Django.
 .. _standalone pip installer: https://pip.pypa.io/en/latest/installing.html#install-pip
 
 Installing a distribution-specific package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 Check the :doc:`distribution specific notes </misc/distributions>` to see if
 your platform/distribution provides official Django packages/installers.
@@ -194,7 +194,7 @@ contain the latest release of Django.
 .. _installing-development-version:
 
 Installing the development version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 .. admonition:: Tracking Django development
 
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index b5e706a9b9..ec560941ae 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -11,7 +11,7 @@ designed to be mostly automatic, but you'll need to know when to make
 migrations, when to run them, and the common problems you might run into.
 
 The Commands
-------------
+============
 
 There are several commands which you will use to interact with migrations
 and Django's handling of database schema:
@@ -53,7 +53,7 @@ need those options in some data migrations later on (for example, if you've
 set custom validators).
 
 Backend Support
----------------
+===============
 
 Migrations are supported on all backends that Django ships with, as well
 as any third-party backends if they have programmed in support for schema
@@ -63,7 +63,7 @@ However, some databases are more capable than others when it comes to
 schema migrations; some of the caveats are covered below.
 
 PostgreSQL
-~~~~~~~~~~
+----------
 
 PostgreSQL is the most capable of all the databases here in terms of schema
 support; the only caveat is that adding columns with default values will
@@ -73,7 +73,7 @@ For this reason, it's recommended you always create new columns with
 ``null=True``, as this way they will be added immediately.
 
 MySQL
-~~~~~
+-----
 
 MySQL lacks support for transactions around schema alteration operations,
 meaning that if a migration fails to apply you will have to manually unpick
@@ -92,7 +92,7 @@ covers. This means that indexes that are possible on other backends will
 fail to be created under MySQL.
 
 SQLite
-~~~~~~
+------
 
 SQLite has very little built-in schema alteration support, and so Django
 attempts to emulate it by:
@@ -110,7 +110,7 @@ developers to use SQLite on their local machines to develop less complex
 Django projects without the need for a full database.
 
 Workflow
---------
+========
 
 Working with migrations is simple. Make changes to your models - say, add
 a field and remove a model - and then run :djadmin:`makemigrations`::
@@ -148,7 +148,7 @@ one, you can use the :option:`makemigrations --name` option::
     $ python manage.py makemigrations --name changed_my_model your_app_label
 
 Version control
-~~~~~~~~~~~~~~~
+---------------
 
 Because migrations are stored in version control, you'll occasionally
 come across situations where you and another developer have both committed
@@ -168,7 +168,7 @@ yourself - don't worry, this isn't difficult, and is explained more in
 :ref:`migration-files` below.
 
 Dependencies
-------------
+============
 
 While migrations are per-app, the tables and relationships implied by
 your models are too complex to be created for just one app at a time. When
@@ -192,7 +192,7 @@ will be.
 .. _migration-files:
 
 Migration files
----------------
+===============
 
 Migrations are stored as an on-disk format, referred to here as
 "migration files". These files are actually just normal Python files with
@@ -238,7 +238,7 @@ more complex operations are not autodetectable and are only available via
 a hand-written migration, so don't be scared about editing them if you have to.
 
 Custom fields
-~~~~~~~~~~~~~
+-------------
 
 You can't modify the number of positional arguments in an already migrated
 custom field without raising a ``TypeError``. The old migration will call the
@@ -249,7 +249,7 @@ argument, please create a keyword argument and add something like
 .. _using-managers-in-migrations:
 
 Model managers
-~~~~~~~~~~~~~~
+--------------
 
 You can optionally serialize managers into migrations and have them available
 in :class:`~django.db.migrations.operations.RunPython` operations. This is done
@@ -275,7 +275,7 @@ Please refer to the notes about :ref:`historical-models` in migrations to see
 the implications that come along.
 
 Initial migrations
-~~~~~~~~~~~~~~~~~~
+------------------
 
 .. attribute:: Migration.initial
 
@@ -301,7 +301,7 @@ and fake-applies the migration if so. Without ``--fake-initial``, initial
 migrations are treated no differently from any other migration.
 
 Adding migrations to apps
--------------------------
+=========================
 
 Adding migrations to new apps is straightforward - they come preconfigured to
 accept migrations, and so just run :djadmin:`makemigrations` once you've made
@@ -333,7 +333,7 @@ Note that this only works given two things:
 .. _historical-models:
 
 Historical models
------------------
+=================
 
 When you run migrations, Django is working from historical versions of your
 models stored in the migration files. If you write Python code using the
@@ -369,7 +369,7 @@ can opt to move them into a superclass.
 .. _migrations-removing-model-fields:
 
 Considerations when removing model fields
------------------------------------------
+=========================================
 
 Similar to the "references to historical functions" considerations described in
 the previous section, removing custom model fields from your project or
@@ -416,7 +416,7 @@ removing the old ones, you should be able to remove the field completely.
 .. _data-migrations:
 
 Data Migrations
----------------
+===============
 
 As well as changing the database schema, you can also use migrations to change
 the data in the database itself, in conjunction with the schema if you want.
@@ -501,7 +501,7 @@ want executed when migrating backwards. If this callable is omitted, migrating
 backwards will raise an exception.
 
 Accessing models from other apps
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 When writing a ``RunPython`` function that uses models from apps other than the
 one in which the migration is located, the migration's ``dependencies``
@@ -528,7 +528,7 @@ added a dependency that specifies the last migration of ``app2``::
         ]
 
 More advanced migrations
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 If you're interested in the more advanced migration operations, or want
 to be able to write your own, see the :doc:`migration operations reference
@@ -538,7 +538,7 @@ to be able to write your own, see the :doc:`migration operations reference
 .. _migration-squashing:
 
 Squashing migrations
---------------------
+====================
 
 You are encouraged to make migrations freely and not worry about how many you
 have; the migration code is optimized to deal with hundreds at a time without
@@ -629,7 +629,7 @@ You must then transition the squashed migration to a normal migration by:
 .. _migration-serializing:
 
 Serializing values
-------------------
+==================
 
 Migrations are just Python files containing the old definitions of your models
 - thus, to write them, Django must take the current state of your models and
@@ -693,7 +693,7 @@ the main module body, rather than the class body.
 .. _custom-deconstruct-method:
 
 Adding a deconstruct() method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 You can let Django serialize your own custom class instances by giving the class
 a ``deconstruct()`` method. It takes no arguments, and should return a tuple
@@ -745,7 +745,7 @@ way into your constructor, and then returns those arguments exactly when
 deconstruct() is called.
 
 Supporting Python 2 and 3
--------------------------
+=========================
 
 In order to generate migrations that support both Python 2 and 3, all string
 literals used in your models and fields (e.g. ``verbose_name``,
@@ -765,7 +765,7 @@ changes as it converts all the bytestring attributes to text strings; this is
 normal and should only happen once.
 
 Supporting multiple Django versions
------------------------------------
+===================================
 
 If you are the maintainer of a third-party app with models, you may need to
 ship migrations that support multiple Django versions. In this case, you should
diff --git a/docs/topics/performance.txt b/docs/topics/performance.txt
index 6725a624eb..bfed5969ef 100644
--- a/docs/topics/performance.txt
+++ b/docs/topics/performance.txt
@@ -53,7 +53,7 @@ It's no good just guessing or assuming where the inefficiencies lie in your
 code.
 
 Django tools
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 `django-debug-toolbar
 <https://github.com/django-debug-toolbar/django-debug-toolbar/>`_ is a very
@@ -65,7 +65,7 @@ Third-party panels are also available for the toolbar, that can (for example)
 report on cache performance and template rendering times.
 
 Third-party services
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 There are a number of free services that will analyze and report on the
 performance of your site's pages from the perspective of a remote HTTP client,
@@ -96,7 +96,7 @@ most skills, learning what "looks right" takes practice, but one of the most
 useful guidelines is:
 
 Work at the appropriate level
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Django offers many different ways of approaching things, but just because it's
 possible to do something in a certain way doesn't mean that it's the most
@@ -259,13 +259,13 @@ Django comes with a few helpful pieces of :doc:`middleware </ref/middleware>`
 that can help optimize your site's performance. They include:
 
 :class:`~django.middleware.http.ConditionalGetMiddleware`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Adds support for modern browsers to conditionally GET responses based on the
 ``ETag`` and ``Last-Modified`` headers.
 
 :class:`~django.middleware.gzip.GZipMiddleware`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Compresses responses for all modern browsers, saving bandwidth and transfer
 time. Note that GZipMiddleware is currently considered a security risk, and is
@@ -276,7 +276,7 @@ Sessions
 --------
 
 Using cached sessions
-^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~
 
 :ref:`Using cached sessions <cached-sessions-backend>` may be a way to increase
 performance by eliminating the need to load session data from a slower storage
@@ -290,7 +290,7 @@ Static files, which by definition are not dynamic, make an excellent target for
 optimization gains.
 
 :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By taking advantage of web browsers' caching abilities, you can
 eliminate network hits entirely for a given file after the initial download.
@@ -302,7 +302,7 @@ long-term without missing future changes - when a file changes, so will the
 tag, so browsers will reload the asset automatically.
 
 "Minification"
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 Several third-party Django tools and packages provide the ability to "minify"
 HTML, CSS, and JavaScript. They remove unnecessary whitespace, newlines, and
@@ -410,7 +410,7 @@ performance gains for your application to outweigh the potential risks.
 With these caveats in mind, you should be aware of:
 
 `PyPy <http://pypy.org/>`_
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `PyPy <http://pypy.org/>`_ is an implementation of Python in Python itself (the
 'standard' Python implementation is in C). PyPy can offer substantial
@@ -422,7 +422,7 @@ Django is compatible, but you will need to check the compatibility of other
 libraries you rely on.
 
 C implementations of Python libraries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some Python libraries are also implemented in C, and can be much faster. They
 aim to offer the same APIs. Note that compatibility issues and behavior
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index ec80efafc0..ce6d7a4ab2 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -13,7 +13,7 @@ serializer to handle any format (text-based or not).
     form, you could use the :djadmin:`dumpdata` management command.
 
 Serializing data
-----------------
+================
 
 At the highest level, serializing data is a very simple operation::
 
@@ -50,7 +50,7 @@ This is useful if you want to serialize data directly to a file-like object
 .. _subset-of-fields:
 
 Subset of fields
-~~~~~~~~~~~~~~~~
+----------------
 
 If you only want a subset of fields to be serialized, you can
 specify a ``fields`` argument to the serializer::
@@ -69,7 +69,7 @@ be serialized.
     model, the deserializer will not be able to save deserialized instances.
 
 Inherited Models
-~~~~~~~~~~~~~~~~
+----------------
 
 If you have a model that is defined using an :ref:`abstract base class
 <abstract-base-classes>`, you don't have to do anything special to serialize
@@ -102,7 +102,7 @@ serialize the ``Place`` models as well::
     data = serializers.serialize('xml', all_objects)
 
 Deserializing data
-------------------
+==================
 
 Deserializing data is also a fairly simple operation::
 
@@ -147,7 +147,7 @@ argument is passed in as ``True``::
 .. _serialization-formats:
 
 Serialization formats
----------------------
+=====================
 
 Django supports a number of serialization formats, some of which require you
 to install third-party Python modules:
@@ -167,7 +167,7 @@ Identifier  Information
 .. _PyYAML: http://www.pyyaml.org/
 
 XML
-~~~
+---
 
 The basic XML serialization format is quite simple::
 
@@ -226,7 +226,7 @@ This example links the given user with the permission models with PKs 46 and 47.
 .. _serialization-formats-json:
 
 JSON
-~~~~
+----
 
 When staying with the same example data as before it would be serialized as
 JSON in the following way::
@@ -275,7 +275,7 @@ Also note that GeoDjango provides a :doc:`customized GeoJSON serializer
 .. _ecma-262: http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15
 
 YAML
-~~~~
+----
 
 YAML serialization looks quite similar to JSON. The object list is serialized
 as a sequence mappings with the keys "pk", "model" and "fields". Each field is
@@ -290,7 +290,7 @@ Referential fields are again just represented by the PK or sequence of PKs.
 .. _topics-serialization-natural-keys:
 
 Natural keys
-------------
+============
 
 The default serialization strategy for foreign keys and many-to-many relations
 is to serialize the value of the primary key(s) of the objects in the relation.
@@ -326,7 +326,7 @@ key is a tuple of values that can be used to uniquely identify an
 object instance without using the primary key value.
 
 Deserialization of natural keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Consider the following two models::
 
@@ -419,7 +419,7 @@ model's manager has a ``get_by_natural_key()`` method and if so, use it to
 populate the deserialized object's primary key.
 
 Serialization of natural keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 So how do you get Django to emit a natural key when serializing an object?
 Firstly, you need to add another method -- this time to the model itself::
@@ -487,7 +487,7 @@ command line flags to generate natural keys.
     key values, just don't define the ``get_by_natural_key()`` method.
 
 Dependencies during serialization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 Since natural keys rely on database lookups to resolve references, it
 is important that the data exists before it is referenced. You can't make
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 9c50aa0f9f..96332d60b8 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -9,7 +9,7 @@ Django provides a small set of tools that come in handy when writing tests.
 .. _test-client:
 
 The test client
----------------
+===============
 
 The test client is a Python class that acts as a dummy Web browser, allowing
 you to test your views and interact with your Django-powered application
@@ -42,7 +42,7 @@ short:
 A comprehensive test suite should use a combination of both test types.
 
 Overview and a quick example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 To use the test client, instantiate ``django.test.Client`` and retrieve
 Web pages::
@@ -105,7 +105,7 @@ Note a few important things about how the test client works:
       >>> csrf_client = Client(enforce_csrf_checks=True)
 
 Making requests
-~~~~~~~~~~~~~~~
+---------------
 
 Use the ``django.test.Client`` class to make requests.
 
@@ -415,7 +415,7 @@ Use the ``django.test.Client`` class to make requests.
         to come from an :class:`~django.contrib.auth.models.AnonymousUser`.
 
 Testing responses
-~~~~~~~~~~~~~~~~~
+-----------------
 
 The ``get()`` and ``post()`` methods both return a ``Response`` object. This
 ``Response`` object is *not* the same as the ``HttpResponse`` object returned
@@ -526,7 +526,7 @@ of any settings in the HTTP headers. For example, you could determine the
 content type of a response using ``response['Content-Type']``.
 
 Exceptions
-~~~~~~~~~~
+----------
 
 If you point the test client at a view that raises an exception, that exception
 will be visible in the test case. You can then use a standard ``try ... except``
@@ -540,7 +540,7 @@ exceptions internally and converts them into the appropriate HTTP response
 codes. In these cases, you can check ``response.status_code`` in your test.
 
 Persistent state
-~~~~~~~~~~~~~~~~
+----------------
 
 The test client is stateful. If a response returns a cookie, then that cookie
 will be stored in the test client and sent with all subsequent ``get()`` and
@@ -574,7 +574,7 @@ can access these properties as part of a test condition.
             session.save()
 
 Example
-~~~~~~~
+-------
 
 The following is a simple unit test using the test client::
 
@@ -603,7 +603,7 @@ The following is a simple unit test using the test client::
 .. _django-testcase-subclasses:
 
 Provided test case classes
---------------------------
+==========================
 
 Normal Python unit test classes extend a base class of
 :class:`unittest.TestCase`. Django provides a few extensions of this base class:
@@ -618,7 +618,7 @@ Normal Python unit test classes extend a base class of
    Hierarchy of Django unit testing classes
 
 SimpleTestCase
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: SimpleTestCase()
 
@@ -702,7 +702,7 @@ then you should use :class:`~django.test.TransactionTestCase` or
     calling ``super()`` to avoid this.
 
 TransactionTestCase
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. class:: TransactionTestCase()
 
@@ -743,7 +743,7 @@ to test the effects of commit and rollback:
 ``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase`.
 
 TestCase
-~~~~~~~~
+--------
 
 .. class:: TestCase()
 
@@ -812,7 +812,7 @@ additions, including:
 .. _live-test-server:
 
 LiveServerTestCase
-~~~~~~~~~~~~~~~~~~
+------------------
 
 .. class:: LiveServerTestCase()
 
@@ -966,10 +966,10 @@ out the `full reference`_ for more details.
     .. _Selenium documentation: http://seleniumhq.org/docs/04_webdriver_advanced.html#explicit-waits
 
 Test cases features
--------------------
+===================
 
 Default test client
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. attribute:: SimpleTestCase.client
 
@@ -1008,7 +1008,7 @@ This means, instead of instantiating a ``Client`` in each test::
             self.assertEqual(response.status_code, 200)
 
 Customizing the test client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 .. attribute:: SimpleTestCase.client_class
 
@@ -1032,7 +1032,7 @@ attribute::
 .. _topics-testing-fixtures:
 
 Fixture loading
-~~~~~~~~~~~~~~~
+---------------
 
 .. attribute:: TransactionTestCase.fixtures
 
@@ -1089,7 +1089,7 @@ using multiple databases and set :attr:`multi_db=True
 <TransactionTestCase.multi_db>`, fixtures will be loaded into all databases.
 
 URLconf configuration
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 If your application provides views, you may want to include tests that use the
 test client to exercise those views. However, an end user is free to deploy the
@@ -1101,7 +1101,7 @@ particular URL. Decorate your test class or test method with
 .. _emptying-test-outbox:
 
 Multi-database support
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 .. attribute:: TransactionTestCase.multi_db
 
@@ -1139,7 +1139,7 @@ If ``multi_db=True``, fixtures are loaded into all databases.
 .. _overriding-settings:
 
 Overriding settings
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. warning::
 
@@ -1315,7 +1315,7 @@ MEDIA_ROOT, DEFAULT_FILE_STORAGE Default file storage
 ================================ ========================
 
 Emptying the test outbox
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 If you use any of Django's custom ``TestCase`` classes, the test runner will
 clear the contents of the test email outbox at the start of each test case.
@@ -1325,7 +1325,7 @@ For more detail on email services during tests, see `Email services`_ below.
 .. _assertions:
 
 Assertions
-~~~~~~~~~~
+----------
 
 As Python's normal :class:`unittest.TestCase` class implements assertion methods
 such as :meth:`~unittest.TestCase.assertTrue` and
@@ -1616,7 +1616,7 @@ your test suite.
 .. _topics-testing-email:
 
 Email services
---------------
+==============
 
 If any of your Django views send email using :doc:`Django's email
 functionality </topics/email>`, you probably don't want to send email each time
@@ -1673,7 +1673,7 @@ manually, assign the empty list to ``mail.outbox``::
 .. _topics-testing-management-commands:
 
 Management Commands
--------------------
+===================
 
 Management commands can be tested with the
 :func:`~django.core.management.call_command` function. The output can be
@@ -1692,7 +1692,7 @@ redirected into a ``StringIO`` instance::
 .. _skipping-tests:
 
 Skipping tests
---------------
+==============
 
 .. currentmodule:: django.test