[1.9.x] Fixed #26020 -- Normalized header stylings in docs.

Backport of bca9faae95db2a92e540fbd08505c134639916fe from master

9 files changed, 45 insertions, 41 deletions

diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt
index 5140911591..3d5e357395 100644
--- a/docs/howto/custom-file-storage.txt
+++ b/docs/howto/custom-file-storage.txt
@@ -1,3 +1,4 @@
+===============================
 Writing a custom storage system
 ===============================
 
diff --git a/docs/howto/custom-lookups.txt b/docs/howto/custom-lookups.txt
index a795326c21..87a388283a 100644
--- a/docs/howto/custom-lookups.txt
+++ b/docs/howto/custom-lookups.txt
@@ -10,7 +10,7 @@ explains how to write custom lookups and how to alter the working of existing
 lookups. For the API references of lookups, see the :doc:`/ref/models/lookups`.
 
 A simple lookup example
-~~~~~~~~~~~~~~~~~~~~~~~
+=======================
 
 Let's start with a simple custom lookup. We will write a custom lookup ``ne``
 which works opposite to ``exact``. ``Author.objects.filter(name__ne='Jack')``
@@ -97,7 +97,7 @@ the parameters for the query. We then return a tuple containing the generated
 SQL string and the parameters.
 
 A simple transformer example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
 
 The custom lookup above is great, but in some cases you may want to be able to
 chain lookups together. For example, let's suppose we are building an
@@ -163,8 +163,8 @@ be done by adding an ``output_field`` attribute to the transform::
 This ensures that further lookups like ``abs__lte`` behave as they would for
 a ``FloatField``.
 
-Writing an efficient abs__lt lookup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Writing an efficient ``abs__lt`` lookup
+=======================================
 
 When using the above written ``abs`` lookup, the SQL produced will not use
 indexes efficiently in some cases. In particular, when we use
@@ -215,7 +215,7 @@ transformations in Python.
     be very efficient.
 
 A bilateral transformer example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===============================
 
 The ``AbsoluteValue`` example we discussed previously is a transformation which
 applies to the left-hand side of the lookup. There may be some cases where you
@@ -252,7 +252,7 @@ insensitive query like this::
     SELECT ... WHERE UPPER("author"."name") = UPPER('doe')
 
 Writing alternative implementations for existing lookups
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================
 
 Sometimes different database vendors require different SQL for the same
 operation. For this example we will rewrite a custom implementation for
@@ -280,7 +280,7 @@ methods, and then falls back to ``as_sql``. The vendor names for the in-built
 backends are ``sqlite``, ``postgresql``, ``oracle`` and ``mysql``.
 
 How Django determines the lookups and transforms which are used
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===============================================================
 
 In some cases you may wish to dynamically change which ``Transform`` or
 ``Lookup`` is returned based on the name passed in, rather than fixing it. As
diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 5beed7637e..08e666d86c 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -11,7 +11,7 @@ defining custom tags and filters using Python, and then make them
 available to your templates using the :ttag:`{% load %}<load>` tag.
 
 Code layout
------------
+===========
 
 The most common place to specify custom template tags and filters is inside
 a Django app. If they relate to an existing app, it makes sense to bundle them
@@ -89,7 +89,7 @@ an application.
 .. _howto-writing-custom-template-filters:
 
 Writing custom template filters
--------------------------------
+===============================
 
 Custom filters are just Python functions that take one or two arguments:
 
@@ -127,7 +127,7 @@ your function. Example::
         return value.lower()
 
 Registering custom filters
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 .. method:: django.template.Library.filter()
 
@@ -162,7 +162,7 @@ are described in :ref:`filters and auto-escaping <filters-auto-escaping>` and
 :ref:`filters and time zones <filters-timezones>` below.
 
 Template filters that expect strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 
 .. method:: django.template.defaultfilters.stringfilter()
 
@@ -187,7 +187,7 @@ methods).
 .. _filters-auto-escaping:
 
 Filters and auto-escaping
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 When writing a custom filter, give some thought to how the filter will interact
 with Django's auto-escaping behavior. Note that three types of strings can be
@@ -378,7 +378,7 @@ Template filter code falls into one of two situations:
 .. _filters-timezones:
 
 Filters and time zones
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 If you write a custom filter that operates on :class:`~datetime.datetime`
 objects, you'll usually register it with the ``expects_localtime`` flag set to
@@ -399,7 +399,7 @@ conversions in templates <time-zones-in-templates>`.
 .. _howto-writing-custom-template-tags:
 
 Writing custom template tags
-----------------------------
+============================
 
 Tags are more complex than filters, because tags can do anything. Django
 provides a number of shortcuts that make writing most types of tags easier.
@@ -409,7 +409,7 @@ scratch for those cases when the shortcuts aren't powerful enough.
 .. _howto-custom-template-tags-simple-tags:
 
 Simple tags
-~~~~~~~~~~~
+-----------
 
 .. method:: django.template.Library.simple_tag()
 
@@ -516,7 +516,7 @@ you see fit:
 .. _howto-custom-template-tags-inclusion-tags:
 
 Inclusion tags
-~~~~~~~~~~~~~~
+--------------
 
 .. method:: django.template.Library.inclusion_tag()
 
@@ -650,7 +650,7 @@ positional arguments. For example:
     {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}
 
 Assignment tags
-~~~~~~~~~~~~~~~
+---------------
 
 .. method:: django.template.Library.assignment_tag()
 
@@ -679,14 +679,14 @@ followed by the variable name, and output it yourself where you see fit:
     <p>The time is {{ the_time }}.</p>
 
 Advanced custom template tags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 Sometimes the basic features for custom template tag creation aren't enough.
 Don't worry, Django gives you complete access to the internals required to build
 a template tag from the ground up.
 
 A quick overview
-~~~~~~~~~~~~~~~~
+----------------
 
 The template system works in a two-step process: compiling and rendering. To
 define a custom template tag, you specify how the compilation works and how
@@ -704,7 +704,7 @@ converted into a ``Node`` (the compilation function), and what the node's
 ``render()`` method does.
 
 Writing the compilation function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 For each template tag the template parser encounters, it calls a Python
 function with the tag contents and the parser object itself. This function is
@@ -774,7 +774,7 @@ Notes:
   engine too slow. It's low-level because that's fastest.
 
 Writing the renderer
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 The second step in writing custom tags is to define a ``Node`` subclass that
 has a ``render()`` method.
@@ -813,7 +813,7 @@ without having to be parsed multiple times.
 .. _tags-auto-escaping:
 
 Auto-escaping considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 The output from template tags is **not** automatically run through the
 auto-escaping filters (with the exception of
@@ -864,7 +864,7 @@ tag is used inside a :ttag:`{% autoescape off %}<autoescape>` block.
 .. _template_tag_thread_safety:
 
 Thread-safety considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 Once a node is parsed, its ``render`` method may be called any number of times.
 Since Django is sometimes run in multi-threaded environments, a single node may
@@ -947,7 +947,7 @@ like the current iteration of the ``CycleNode``, should be stored in the
     variables, make ``render_context[self]`` a dictionary.
 
 Registering the tag
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 Finally, register the tag with your module's ``Library`` instance, as explained
 in :ref:`writing custom template filters<howto-writing-custom-template-tags>`
@@ -976,7 +976,7 @@ If you leave off the ``name`` argument, as in the second example above, Django
 will use the function's name as the tag name.
 
 Passing template variables to the tag
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 Although you can pass any number of arguments to a template tag using
 ``token.split_contents()``, the arguments are all unpacked as
@@ -1043,7 +1043,7 @@ Variable resolution will throw a ``VariableDoesNotExist`` exception if it
 cannot resolve the string passed to it in the current context of the page.
 
 Setting a variable in the context
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 The above examples simply output a value. Generally, it's more flexible if your
 template tags set template variables instead of outputting values. That way,
@@ -1134,7 +1134,7 @@ context-updating template tag, consider using the
 the tag results to a template variable.
 
 Parsing until another block tag
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Template tags can work in tandem. For instance, the standard
 :ttag:`{% comment %}<comment>` tag hides everything until ``{% endcomment %}``.
@@ -1178,7 +1178,7 @@ After ``parser.parse()`` is called, the parser hasn't yet "consumed" the
 ``{% comment %}`` and ``{% endcomment %}`` is ignored.
 
 Parsing until another block tag, and saving contents
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
 
 In the previous example, ``do_comment()`` discarded everything between
 ``{% comment %}`` and ``{% endcomment %}``. Instead of doing that, it's
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
index 4acde03699..8ffda2cf63 100644
--- a/docs/howto/deployment/index.txt
+++ b/docs/howto/deployment/index.txt
@@ -1,3 +1,4 @@
+================
 Deploying Django
 ================
 
diff --git a/docs/howto/deployment/wsgi/index.txt b/docs/howto/deployment/wsgi/index.txt
index 27243e248c..2579df0c6a 100644
--- a/docs/howto/deployment/wsgi/index.txt
+++ b/docs/howto/deployment/wsgi/index.txt
@@ -22,7 +22,7 @@ Django includes getting-started documentation for the following WSGI servers:
    uwsgi
 
 The ``application`` object
---------------------------
+==========================
 
 The key concept of deploying with WSGI is the ``application`` callable which
 the application server uses to communicate with your code. It's commonly
@@ -42,7 +42,7 @@ set to ``<project_name>.wsgi.application``, which points to the ``application``
 callable in :file:`<project_name>/wsgi.py`.
 
 Configuring the settings module
--------------------------------
+===============================
 
 When the WSGI server loads your application, Django needs to import the
 settings module — that's where your entire application is defined.
@@ -68,7 +68,7 @@ If this variable isn't set, the default :file:`wsgi.py` sets it to
 
 
 Applying WSGI middleware
-------------------------
+========================
 
 To apply `WSGI middleware`_ you can simply wrap the application object. For
 instance you could add these lines at the bottom of :file:`wsgi.py`::
diff --git a/docs/howto/error-reporting.txt b/docs/howto/error-reporting.txt
index d27f734398..fc043375d4 100644
--- a/docs/howto/error-reporting.txt
+++ b/docs/howto/error-reporting.txt
@@ -1,3 +1,4 @@
+===============
 Error reporting
 ===============
 
@@ -12,10 +13,10 @@ You need to keep track of errors that occur in deployed sites, so Django can be
 configured to create reports with details about those errors.
 
 Email reports
--------------
+=============
 
 Server errors
-~~~~~~~~~~~~~
+-------------
 
 When :setting:`DEBUG` is ``False``, Django will email the users listed in the
 :setting:`ADMINS` setting whenever your code raises an unhandled exception and
@@ -49,7 +50,7 @@ To activate this behavior, put the email addresses of the recipients in the
     </topics/logging>`.
 
 404 errors
-~~~~~~~~~~
+----------
 
 Django can also be configured to email errors about broken links (404 "page
 not found" errors). Django sends emails about 404 errors when:
@@ -119,7 +120,7 @@ and override its methods.
 .. _filtering-error-reports:
 
 Filtering error reports
------------------------
+=======================
 
 .. warning::
 
@@ -130,7 +131,7 @@ Filtering error reports
     through email).
 
 Filtering sensitive information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 .. currentmodule:: django.views.decorators.debug
 
@@ -231,7 +232,7 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
 .. _custom-error-reports:
 
 Custom error reports
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 All :func:`sensitive_variables` and :func:`sensitive_post_parameters` do is,
 respectively, annotate the decorated function with the names of sensitive
diff --git a/docs/howto/index.txt b/docs/howto/index.txt
index f06cd6b627..89e3192810 100644
--- a/docs/howto/index.txt
+++ b/docs/howto/index.txt
@@ -1,3 +1,4 @@
+===============
 "How-to" guides
 ===============
 
diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt
index f341482167..2d9fded5c2 100644
--- a/docs/howto/outputting-csv.txt
+++ b/docs/howto/outputting-csv.txt
@@ -76,7 +76,7 @@ mention:
 .. _streaming-csv-files:
 
 Streaming large CSV files
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 When dealing with views that generate very large responses, you might want to
 consider using Django's :class:`~django.http.StreamingHttpResponse` instead.
diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt
index 5527302fa8..096b5e3b15 100644
--- a/docs/howto/writing-migrations.txt
+++ b/docs/howto/writing-migrations.txt
@@ -9,7 +9,7 @@ migrations, see :doc:`the topic guide </topics/migrations>`.
 .. _data-migrations-and-multiple-databases:
 
 Data migrations and multiple databases
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+======================================
 
 When using multiple databases, you may need to figure out whether or not to
 run a migration against a particular database. For example, you may want to
@@ -74,7 +74,7 @@ practice to pass ``model_name`` as a hint to make it as transparent as possible
 to the router. This is especially important for reusable and third-party apps.
 
 Migrations that add unique fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================
 
 Applying a "plain" migration that adds a unique non-nullable field to a table
 with existing rows will raise an error because the value used to populate
@@ -187,7 +187,7 @@ the respective field according to your needs.
   ``RunPython`` will have their original ``uuid``’s overwritten.
 
 Controlling the order of migrations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===================================
 
 Django determines the order in which migrations should be applied not by the
 filename of each migration, but by building a graph using two properties on the