Fixed #26020 -- Normalized header stylings in docs.

docs/contents.txt

@@ -1,5 +1,3 @@
-.. _contents:
-
 =============================
 Django documentation contents
 =============================
@@ -27,4 +25,4 @@ Indices, glossary and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`glossary`
+* :doc:`glossary`

docs/faq/admin.txt

@@ -1,8 +1,9 @@
+==============
 FAQ: The admin
 ==============
 
 I can't log in. When I enter a valid username and password, it just brings up the login page again, with no error messages.
----------------------------------------------------------------------------------------------------------------------------
+===========================================================================================================================
 
 The login cookie isn't being set correctly, because the domain of the cookie
 sent out by Django doesn't match the domain in your browser. Try these two
@@ -14,7 +15,7 @@ things:
   should set :setting:`SESSION_COOKIE_DOMAIN` = 'www.example.com'.
 
 I can't log in. When I enter a valid username and password, it brings up the login page again, with a "Please enter a correct username and password" error.
------------------------------------------------------------------------------------------------------------------------------------------------------------
+===========================================================================================================================================================
 
 If you're sure your username and password are correct, make sure your user
 account has :attr:`~django.contrib.auth.models.User.is_active` and
@@ -22,7 +23,7 @@ account has :attr:`~django.contrib.auth.models.User.is_active` and
 only allows access to users with those two fields both set to True.
 
 How do I automatically set a field's value to the user who last edited the object in the admin?
------------------------------------------------------------------------------------------------
+===============================================================================================
 
 The :class:`~django.contrib.admin.ModelAdmin` class provides customization hooks
 that allow you to transform an object as it saved, using details from the
@@ -32,7 +33,7 @@ object to reflect the user that edited it. See :ref:`the documentation on
 ModelAdmin methods <model-admin-methods>` for an example.
 
 How do I limit admin access so that objects can only be edited by the users who created them?
----------------------------------------------------------------------------------------------
+=============================================================================================
 
 The :class:`~django.contrib.admin.ModelAdmin` class also provides customization
 hooks that allow you to control the visibility and editability of objects in the
@@ -42,13 +43,13 @@ admin. Using the same trick of extracting the user from the request, the
 control the visibility and editability of objects in the admin.
 
 My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_wsgi.
----------------------------------------------------------------------------------------------------------------------------
+=========================================================================================================================
 
 See :ref:`serving the admin files <serving-the-admin-files>`
 in the "How to use Django with mod_wsgi" documentation.
 
 My "list_filter" contains a ManyToManyField, but the filter doesn't display.
-----------------------------------------------------------------------------
+============================================================================
 
 Django won't bother displaying the filter for a ``ManyToManyField`` if there
 are fewer than two related objects.
@@ -59,7 +60,7 @@ database, it won't display a "Site" filter. In that case, filtering by site
 would be meaningless.
 
 Some objects aren't appearing in the admin.
--------------------------------------------
+===========================================
 
 Inconsistent row counts may be caused by missing foreign key values or a
 foreign key field incorrectly set to :attr:`null=False
@@ -71,7 +72,7 @@ shown in the admin changelist because the Django model is declaring an
 integrity constraint that is not implemented at the database level.
 
 How can I customize the functionality of the admin interface?
--------------------------------------------------------------
+=============================================================
 
 You've got several options. If you want to piggyback on top of an add/change
 form that Django automatically generates, you can attach arbitrary JavaScript
@@ -89,7 +90,7 @@ If you want to customize the look-and-feel of the admin interface, read the
 next question.
 
 The dynamically-generated admin site is ugly! How can I change it?
-------------------------------------------------------------------
+==================================================================
 
 We like it, but if you don't agree, you can modify the admin site's
 presentation by editing the CSS stylesheet and/or associated image files. The
@@ -97,7 +98,7 @@ site is built using semantic HTML and plenty of CSS hooks, so any changes you'd
 like to make should be possible by editing the stylesheet.
 
 What browsers are supported for using the admin?
-------------------------------------------------
+================================================
 
 The admin provides a fully-functional experience to `YUI's A-grade`_ browsers,
 with the notable exception of IE6, which is not supported.

docs/faq/contributing.txt

@@ -1,14 +1,15 @@
+======================
 FAQ: Contributing code
 ======================
 
 How can I get started contributing code to Django?
---------------------------------------------------
+==================================================
 
 Thanks for asking! We've written an entire document devoted to this question.
 It's titled :doc:`Contributing to Django </internals/contributing/index>`.
 
 I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch?
---------------------------------------------------------------------------------------------
+============================================================================================
 
 Don't worry: We're not ignoring you!
 
@@ -43,7 +44,7 @@ we'll just close the ticket. So if your ticket is still open, it doesn't mean
 we're ignoring you; it just means we haven't had time to look at it yet.
 
 When and how might I remind the core team of a patch I care about?
-------------------------------------------------------------------
+==================================================================
 
 A polite, well-timed message to the mailing list is one way to get attention.
 To determine the right time, you need to keep an eye on the schedule. If you
@@ -70,7 +71,7 @@ additional attention -- certainly not the attention that you need in order to
 get your pet bug addressed.
 
 But I've reminded you several times and you keep ignoring my patch!
--------------------------------------------------------------------
+===================================================================
 
 Seriously - we're not ignoring you. If your patch stands no chance of
 inclusion in Django, we'll close the ticket. For all the other tickets, we

docs/faq/general.txt

@@ -1,8 +1,9 @@
+============
 FAQ: General
 ============
 
 Why does this project exist?
-----------------------------
+============================
 
 Django grew from a very practical need: World Online, a newspaper Web
 operation, is responsible for building intensive Web applications on journalism
@@ -29,7 +30,7 @@ thrilled to be able to give something back to the open-source community.
 .. _PostgreSQL: http://www.postgresql.org/
 
 What does "Django" mean, and how do you pronounce it?
------------------------------------------------------
+=====================================================
 
 Django is named after `Django Reinhardt`_, a gypsy jazz guitarist from the 1930s
 to early 1950s. To this day, he's considered one of the best guitarists of all time.
@@ -44,14 +45,14 @@ We've also recorded an `audio clip of the pronunciation`_.
 .. _audio clip of the pronunciation: http://red-bean.com/~adrian/django_pronunciation.mp3
 
 Is Django stable?
------------------
+=================
 
 Yes, it's quite stable. Companies like Disqus, Instagram, Pinterest, and
 Mozilla have been using Django for many years. Sites built on Django have
 weathered traffic spikes of over 50 thousand hits per second.
 
 Does Django scale?
-------------------
+==================
 
 Yes. Compared to development time, hardware is cheap, and so Django is
 designed to take advantage of as much hardware as you can throw at it.
@@ -64,14 +65,14 @@ application layer. And it ships with a simple-yet-powerful
 :doc:`cache framework </topics/cache>`.
 
 Who's behind this?
-------------------
+==================
 
 Django was originally developed at World Online, the Web department of a
 newspaper in Lawrence, Kansas, USA. Django's now run by an international
 :doc:`team of volunteers </internals/team>`.
 
 Which sites use Django?
------------------------
+=======================
 
 `DjangoSites.org`_ features a constantly growing list of Django-powered sites.
 
@@ -80,7 +81,7 @@ Which sites use Django?
 .. _faq-mtv:
 
 Django appears to be a MVC framework, but you call the Controller the "view", and the View the "template". How come you don't use the standard names?
------------------------------------------------------------------------------------------------------------------------------------------------------
+=====================================================================================================================================================
 
 Well, the standard names are debatable.
 
@@ -110,7 +111,7 @@ regardless of how things are named, Django gets stuff done in a way that's most
 logical to us.
 
 <Framework X> does <feature Y> -- why doesn't Django?
------------------------------------------------------
+=====================================================
 
 We're well aware that there are other awesome Web frameworks out there, and
 we're not averse to borrowing ideas where appropriate. However, Django was
@@ -119,7 +120,7 @@ aware that "because <Framework X> does it" is not going to be sufficient reason
 to add a given feature to Django.
 
 Why did you write all of Django from scratch, instead of using other Python libraries?
---------------------------------------------------------------------------------------
+======================================================================================
 
 When Django was originally written a couple of years ago, Adrian and Simon
 spent quite a bit of time exploring the various Python Web frameworks
@@ -145,7 +146,7 @@ We've documented our philosophies on the
 :doc:`design philosophies page </misc/design-philosophies>`.
 
 Is Django a content-management-system (CMS)?
---------------------------------------------
+============================================
 
 No, Django is not a CMS, or any sort of "turnkey product" in and of itself.
 It's a Web framework; it's a programming tool that lets you build websites.
@@ -162,7 +163,7 @@ means!).
 .. _Drupal: https://drupal.org/
 
 How can I download the Django documentation to read it offline?
----------------------------------------------------------------
+===============================================================
 
 The Django docs are available in the ``docs`` directory of each Django tarball
 release. These docs are in reST (reStructuredText) format, and each text file
@@ -178,7 +179,7 @@ information than the docs that come with the latest Django release.
 .. _stored in revision control: https://github.com/django/django/tree/master/docs/
 
 Where can I find Django developers for hire?
---------------------------------------------
+============================================
 
 Consult our `developers for hire page`_ for a list of Django developers who
 would be happy to help you.
@@ -190,7 +191,7 @@ https://people.djangoproject.com/ .
 .. _developers for hire page: https://code.djangoproject.com/wiki/DevelopersForHire
 
 How do I cite Django?
----------------------
+=====================
 
 It's difficult to give an official citation format, for two reasons: citation
 formats can vary wildly between publications, and citation standards for

docs/faq/help.txt

@@ -1,8 +1,9 @@
+=================
 FAQ: Getting Help
 =================
 
 How do I do X? Why doesn't Y work? Where can I go to get help?
---------------------------------------------------------------
+==============================================================
 
 If this FAQ doesn't contain an answer to your question, you might want to
 try the |django-users| mailing list. Feel free to ask any question related
@@ -16,7 +17,7 @@ active community of helpful individuals who may be able to solve your problem.
 .. _message-does-not-appear-on-django-users:
 
 Why hasn't my message appeared on django-users?
------------------------------------------------
+===============================================
 
 |django-users| has a lot of subscribers. This is good for the community, as
 it means many people are available to contribute answers to questions.
@@ -30,7 +31,7 @@ list might take a little longer to get answered. We apologize for any
 inconvenience that this policy may cause.
 
 Nobody on django-users answered my question! What should I do?
---------------------------------------------------------------
+==============================================================
 
 Try making your question more specific, or provide a better example of your
 problem.
@@ -48,13 +49,13 @@ for discussion of the development of Django itself. Asking a tech support
 question there is considered quite impolite.
 
 I think I've found a bug! What should I do?
--------------------------------------------
+===========================================
 
 Detailed instructions on how to handle a potential bug can be found in our
 :ref:`Guide to contributing to Django <reporting-bugs>`.
 
 I think I've found a security problem! What should I do?
---------------------------------------------------------
+========================================================
 
 If you think you've found a security problem with Django, please send a message
 to security@djangoproject.com. This is a private list only open to long-time,

docs/faq/install.txt

@@ -1,8 +1,9 @@
+=================
 FAQ: Installation
 =================
 
 How do I get started?
----------------------
+=====================
 
 #. `Download the code`_.
 #. Install Django (read the :doc:`installation guide </intro/install>`).
@@ -14,7 +15,7 @@ How do I get started?
 .. _ask questions: https://www.djangoproject.com/community/
 
 What are Django's prerequisites?
---------------------------------
+================================
 
 Django requires Python. See the table in the next question for the versions of
 Python that work with each version of Django. Other Python libraries may be
@@ -40,7 +41,7 @@ PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported.
 .. _faq-python-version-support:
 
 What Python version can I use with Django?
-------------------------------------------
+==========================================
 
 ============== ===============
 Django version Python versions
@@ -60,7 +61,7 @@ version of Python ends. For example, Python 3.3 security support ends September
 is the last version to support Python 3.3.
 
 What Python version should I use with Django?
----------------------------------------------
+=============================================
 
 As of Django 1.6, Python 3 support is considered stable and you can safely use
 it in production. See also :doc:`/topics/python3`. However, the community is
@@ -81,7 +82,7 @@ Third-party applications for use with Django are, of course, free to set their
 own version requirements.
 
 Should I use the stable version or development version?
--------------------------------------------------------
+=======================================================
 
 Generally, if you're using code in production, you should be using a
 stable release. The Django project publishes a full stable release

docs/faq/models.txt

@@ -1,10 +1,11 @@
+=========================
 FAQ: Databases and models
 =========================
 
 .. _faq-see-raw-sql-queries:
 
 How can I see the raw SQL queries Django is running?
-----------------------------------------------------
+====================================================
 
 Make sure your Django :setting:`DEBUG` setting is set to ``True``.
 Then, just do this::
@@ -37,12 +38,12 @@ just call ``reset_queries()``, like this::
     reset_queries()
 
 Can I use Django with a pre-existing database?
-----------------------------------------------
+==============================================
 
 Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`.
 
 If I make changes to a model, how do I update the database?
------------------------------------------------------------
+===========================================================
 
 Take a look at Django's support for :mod:`schema migrations
 <django.db.migrations>`.
@@ -52,7 +53,7 @@ If you don't mind clearing data, your project's ``manage.py`` utility has a
 immediately after :djadmin:`migrate` was executed.
 
 Do Django models support multiple-column primary keys?
-------------------------------------------------------
+======================================================
 
 No. Only single-column primary keys are supported.
 
@@ -64,7 +65,7 @@ as the admin interface to work; e.g., you need a simple way of being able to
 specify an object to edit or delete.
 
 Does Django support NoSQL databases?
-------------------------------------
+====================================
 
 NoSQL databases are not officially supported by Django itself. There are,
 however, a number of side project and forks which allow NoSQL functionality in
@@ -76,7 +77,7 @@ You can also take a look on `the wiki page`_ which discusses some alternatives.
 .. _`the wiki page`: https://code.djangoproject.com/wiki/NoSqlSupport
 
 How do I add database-specific options to my CREATE TABLE statements, such as specifying MyISAM as the table type?
-------------------------------------------------------------------------------------------------------------------
+==================================================================================================================
 
 We try to avoid adding special cases in the Django code to accommodate all the
 database-specific options such as table type, etc. If you'd like to use any of

docs/faq/usage.txt

@@ -1,8 +1,9 @@
+=================
 FAQ: Using Django
 =================
 
 Why do I get an error about importing DJANGO_SETTINGS_MODULE?
--------------------------------------------------------------
+=============================================================
 
 Make sure that:
 
@@ -14,7 +15,7 @@ Make sure that:
 * The module doesn't contain syntax errors (of course).
 
 I can't stand your template language. Do I have to use it?
-----------------------------------------------------------
+==========================================================
 
 We happen to think our template engine is the best thing since chunky bacon,
 but we recognize that choosing a template language runs close to religion.
@@ -22,7 +23,7 @@ There's nothing about Django that requires using the template language, so
 if you're attached to Jinja2, Mako, or whatever, feel free to use those.
 
 Do I have to use your model/database layer?
--------------------------------------------
+===========================================
 
 Nope. Just like the template system, the model/database layer is decoupled from
 the rest of the framework.
@@ -32,7 +33,7 @@ use Django's automatically-generated admin site. That app is coupled to the
 Django database layer.
 
 How do I use image and file fields?
------------------------------------
+===================================
 
 Using a :class:`~django.db.models.FileField` or an
 :class:`~django.db.models.ImageField` in a model takes a few steps:
@@ -58,7 +59,7 @@ Using a :class:`~django.db.models.FileField` or an
    ``{{ object.mug_shot.url }}``.
 
 How do I make a variable available to all my templates?
--------------------------------------------------------
+=======================================================
 
 Sometimes your templates just all need the same thing. A common example would
 be dynamically-generated menus. At first glance, it seems logical to simply

docs/glossary.txt

@@ -1,5 +1,3 @@
-.. _glossary:
-
 ========
 Glossary
 ========

docs/howto/custom-file-storage.txt

@@ -1,3 +1,4 @@
+===============================
 Writing a custom storage system
 ===============================
 

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')``
@@ -93,7 +93,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
@@ -159,8 +159,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
@@ -211,7 +211,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
@@ -248,7 +248,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
@@ -276,7 +276,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

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
@@ -376,7 +376,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
@@ -397,7 +397,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.
@@ -407,7 +407,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()
 
@@ -514,7 +514,7 @@ you see fit:
 .. _howto-custom-template-tags-inclusion-tags:
 
 Inclusion tags
-~~~~~~~~~~~~~~
+--------------
 
 .. method:: django.template.Library.inclusion_tag()
 
@@ -648,7 +648,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()
 
@@ -677,14 +677,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
@@ -702,7 +702,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
@@ -772,7 +772,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.
@@ -811,7 +811,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
@@ -853,7 +853,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
@@ -936,7 +936,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>`
@@ -965,7 +965,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
@@ -1032,7 +1032,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,
@@ -1123,7 +1123,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 %}``.
@@ -1167,7 +1167,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

docs/howto/deployment/index.txt

@@ -1,3 +1,4 @@
+================
 Deploying Django
 ================
 

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`::

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

docs/howto/index.txt

@@ -1,3 +1,4 @@
+===============
 "How-to" guides
 ===============
 

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.

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
@@ -72,7 +72,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
@@ -185,7 +185,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

docs/index.txt

@@ -1,6 +1,3 @@
-
-.. _index:
-
 ====================
 Django documentation
 ====================

docs/internals/contributing/bugs-and-features.txt

@@ -32,7 +32,7 @@ general points:
 .. _reporting-bugs:
 
 Reporting bugs
---------------
+==============
 
 Well-written bug reports are *incredibly* helpful. However, there's a certain
 amount of overhead involved in working with any bug tracking system so your
@@ -61,7 +61,7 @@ To understand the lifecycle of your ticket once you have created it, refer to
 :doc:`triaging-tickets`.
 
 Reporting user interface bugs and features
-------------------------------------------
+==========================================
 
 If your bug or feature request touches on anything visual in nature, there
 are a few additional guidelines to follow:
@@ -87,7 +87,7 @@ are a few additional guidelines to follow:
   find your ticket.
 
 Requesting features
--------------------
+===================
 
 We're always trying to make Django better, and your feature requests are a key
 part of that. Here are some tips on how to make a request most effectively:
@@ -128,7 +128,7 @@ See also: :ref:`documenting-new-features`.
 .. _how-we-make-decisions:
 
 How we make decisions
----------------------
+=====================
 
 Whenever possible, we strive for a rough consensus. To that end, we'll often
 have informal votes on |django-developers| about a feature. In these votes we

docs/internals/contributing/committing-code.txt

@@ -10,7 +10,7 @@ who wants to contribute code to Django, have a look at
 .. _handling-pull-requests:
 
 Handling pull requests
-----------------------
+======================
 
 Since Django is now hosted at GitHub, most patches are provided in the form of
 pull requests.
@@ -101,7 +101,7 @@ community, getting work done, and having a usable commit history.
 .. _committing-guidelines:
 
 Committing guidelines
----------------------
+=====================
 
 In addition, please follow the following guidelines when committing code to
 Django's Git repository:
@@ -200,7 +200,7 @@ Django's Git repository:
   to automate this.
 
 Reverting commits
------------------
+=================
 
 Nobody's perfect; mistakes will be committed.
 

docs/internals/contributing/localizing.txt

@@ -9,7 +9,7 @@ and localization infrastructure available to Django applications, described in
 the :doc:`i18n documentation </topics/i18n/index>`.
 
 Translations
-------------
+============
 
 Translations are contributed by Django users worldwide. The translation work is
 coordinated at `Transifex`_.
@@ -53,11 +53,11 @@ translation manager's availability. So don't miss the string freeze period
 to complete and fix the translations for your language!
 
 Formats
--------
+=======
 
 You can also review ``conf/locale/<locale>/formats.py``. This file describes
 the date, time and numbers formatting particularities of your locale. See
-:ref:`format-localization` for details.
+:doc:`/topics/i18n/formatting` for details.
 
 The format files aren't managed by the use of Transifex. To change them, you
 must :doc:`create a patch<writing-code/submitting-patches>` against the
@@ -75,7 +75,7 @@ Django source tree, as for any code change:
 .. _translating-documentation:
 
 Documentation
--------------
+=============
 
 There is also an opportunity to translate the documentation, though this is a
 huge undertaking to complete entirely (you have been warned!). We use the same

docs/internals/contributing/new-contributors.txt

@@ -11,7 +11,7 @@ to get started? This is the section for you.
     tutorial will give you an introduction to the tools and the workflow.
 
 First steps
------------
+===========
 
 Start with these easy tasks to discover Django's development process.
 
@@ -70,7 +70,7 @@ Start with these easy tasks to discover Django's development process.
 
 
 Guidelines
-----------
+==========
 
 As a newcomer on a large project, it's easy to experience frustration. Here's
 some advice to make your work on Django more useful and rewarding.
@@ -138,7 +138,7 @@ some advice to make your work on Django more useful and rewarding.
 .. _new-contributors-faq:
 
 FAQ
----
+===
 
 1. **This ticket I care about has been ignored for days/weeks/months! What can
    I do to get it committed?**

docs/internals/contributing/triaging-tickets.txt

@@ -32,7 +32,7 @@ Django is a community project, and every contribution helps. We can't do this
 without **you**!
 
 Triage workflow
----------------
+===============
 
 Unfortunately, not all bug reports and feature requests in the ticket tracker
 provide all the :doc:`required details<bugs-and-features>`. A number of
@@ -96,20 +96,20 @@ require much much more.
 .. _triage-stages:
 
 Triage stages
--------------
+=============
 
 Below we describe in more detail the various stages that a ticket may flow
 through during its lifetime.
 
 Unreviewed
-~~~~~~~~~~
+----------
 
 The ticket has not been reviewed by anyone who felt qualified to make a
 judgment about whether the ticket contained a valid issue, a viable feature,
 or ought to be closed for any of the various reasons.
 
 Accepted
-~~~~~~~~
+--------
 
 The big gray area! The absolute meaning of "accepted" is that the issue
 described in the ticket is valid and is in some stage of being worked on.
@@ -142,7 +142,7 @@ Beyond that there are several considerations:
   explaining what is needed to improve the code.
 
 Ready For Checkin
-~~~~~~~~~~~~~~~~~
+-----------------
 
 The ticket was reviewed by any member of the community other than the person
 who supplied the patch and found to meet all the requirements for a
@@ -152,7 +152,7 @@ review prior to being committed. See the
 RFC forever! What should I do?"
 
 Someday/Maybe
-~~~~~~~~~~~~~
+-------------
 
 This stage isn't shown on the diagram. It's only used by core developers to
 keep track of high-level ideas or long term feature requests.
@@ -163,12 +163,12 @@ consider adding someday to the framework if an excellent patch is submitted.
 They are not a high priority.
 
 Other triage attributes
------------------------
+=======================
 
 A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
 
 Has patch
-~~~~~~~~~
+---------
 
 This means the ticket has an associated
 :doc:`patch<writing-code/submitting-patches>`. These will be reviewed
@@ -178,20 +178,20 @@ The following three fields (Needs documentation, Needs tests,
 Patch needs improvement) apply only if a patch has been supplied.
 
 Needs documentation
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 This flag is used for tickets with patches that need associated
 documentation. Complete documentation of features is a prerequisite
 before we can check them into the codebase.
 
 Needs tests
-~~~~~~~~~~~
+-----------
 
 This flags the patch as needing associated unit tests. Again, this
 is a required part of a valid patch.
 
 Patch needs improvement
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 This flag means that although the ticket *has* a patch, it's not quite
 ready for checkin. This could mean the patch no longer applies
@@ -199,12 +199,12 @@ cleanly, there is a flaw in the implementation, or that the code
 doesn't meet our standards.
 
 Easy pickings
-~~~~~~~~~~~~~
+-------------
 
 Tickets that would require small, easy, patches.
 
 Type
-~~~~
+----
 
 Tickets should be categorized by *type* between:
 
@@ -219,14 +219,14 @@ Tickets should be categorized by *type* between:
     better, faster, stronger.
 
 Component
-~~~~~~~~~
+---------
 
 Tickets should be classified into *components* indicating which area of
 the Django codebase they belong to. This makes tickets better organized and
 easier to find.
 
 Severity
-~~~~~~~~
+--------
 
 The *severity* attribute is used to identify blockers, that is, issues which
 should get fixed before releasing the next version of Django. Typically those
@@ -235,26 +235,26 @@ causing severe data losses. This attribute is quite rarely used and the vast
 majority of tickets have a severity of "Normal".
 
 Version
-~~~~~~~
+-------
 
 It is possible to use the *version* attribute to indicate in which
 version the reported bug was identified.
 
 UI/UX
-~~~~~
+-----
 
 This flag is used for tickets that relate to User Interface and User
 Experiences questions. For example, this flag would be appropriate for
 user-facing features in forms or the admin interface.
 
 Cc
-~~
+--
 
 You may add your username or email address to this field to be notified when
 new contributions are made to the ticket.
 
 Keywords
-~~~~~~~~
+--------
 
 With this field you may label a ticket with multiple keywords. This can be
 useful, for example, to group several tickets of a same theme. Keywords can
@@ -266,7 +266,7 @@ as "formset", "modelformset", and "ManagementForm".
 .. _closing-tickets:
 
 Closing Tickets
----------------
+===============
 
 When a ticket has completed its useful lifecycle, it's time for it to be
 closed. Closing a ticket is a big responsibility, though. You have to be sure
@@ -338,7 +338,7 @@ developers and bring the issue to |django-developers| instead.
 .. _how-can-i-help-with-triaging:
 
 How can I help with triaging?
------------------------------
+=============================
 
 The triage process is primarily driven by community members. Really,
 **ANYONE** can help.
@@ -422,7 +422,7 @@ the ticket database:
 .. _password reset page: https://www.djangoproject.com/accounts/password/reset/
 
 Bisecting a regression
-----------------------
+======================
 
 .. highlight:: console
 

docs/internals/contributing/writing-code/coding-style.txt

@@ -5,7 +5,7 @@ Coding style
 Please follow these coding standards when writing code for inclusion in Django.
 
 Python style
-------------
+============
 
 * Please conform to the indentation style dictated in the ``.editorconfig``
   file. We recommend using a text editor with `EditorConfig`_ support to avoid
@@ -52,7 +52,7 @@ Python style
   to use regular expression matching.
 
 Imports
--------
+=======
 
 * Use `isort <https://github.com/timothycrosley/isort#readme>`_ to automate
   import sorting using the guidelines below.
@@ -132,7 +132,7 @@ Imports
       from django.views.generic.base import View
 
 Template style
---------------
+==============
 
 * In Django template code, put one (and only one) space between the curly
   brackets and the tag contents.
@@ -150,7 +150,7 @@ Template style
       {{foo}}
 
 View style
-----------
+==========
 
 * In Django views, the first parameter in a view function should be called
   ``request``.
@@ -166,7 +166,7 @@ View style
           # ...
 
 Model style
------------
+===========
 
 * Field names should be all lowercase, using underscores instead of
   camelCase.
@@ -240,7 +240,7 @@ Model style
         )
 
 Use of ``django.conf.settings``
--------------------------------
+===============================
 
 Modules should not in general use settings stored in ``django.conf.settings``
 at the top level (i.e. evaluated when the module is imported). The explanation
@@ -276,7 +276,7 @@ such as ``django.utils.functional.LazyObject``,
 ``django.utils.functional.lazy()`` or ``lambda``.
 
 Miscellaneous
--------------
+=============
 
 * Mark all strings for internationalization; see the :doc:`i18n
   documentation </topics/i18n/index>` for details.
@@ -299,7 +299,7 @@ Miscellaneous
   single trivial change.
 
 JavaScript style
-----------------
+================
 
 For details about the JavaScript code style used by Django, see
 :doc:`javascript`.

docs/internals/contributing/writing-code/javascript.txt

@@ -9,7 +9,7 @@ Please follow these coding standards when writing JavaScript code for inclusion
 in Django.
 
 Code style
-----------
+==========
 
 * Please conform to the indentation style dictated in the ``.editorconfig``
   file. We recommend using a text editor with `EditorConfig`_ support to avoid
@@ -27,7 +27,7 @@ Code style
 .. _javascript-patches:
 
 JavaScript patches
-------------------
+==================
 
 Django's admin system leverages the jQuery framework to increase the
 capabilities of the admin interface. In conjunction, there is an emphasis on
@@ -41,7 +41,7 @@ production use (e.g. ``foo.min.js``). Any links to the file in the codebase
 should point to the compressed version.
 
 Compressing JavaScript
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 To simplify the process of providing optimized JavaScript code, Django
 includes a handy Python script which should be used to create a "minified"
@@ -61,13 +61,13 @@ Please don't forget to run ``compress.py`` and include the ``diff`` of the
 minified scripts when submitting patches for Django's JavaScript.
 
 JavaScript tests
-----------------
+================
 
 Django's JavaScript tests can be run in a browser or from the command line.
 The tests are located in a top level ``js_tests`` directory.
 
 Writing tests
-~~~~~~~~~~~~~
+-------------
 
 Django's JavaScript tests use `QUnit`_. Here is an example test module:
 
@@ -101,12 +101,12 @@ Please consult the QUnit documentation for information on the types of
 `assertions supported by QUnit <https://api.qunitjs.com/category/assert/>`_.
 
 Running tests
-~~~~~~~~~~~~~
+-------------
 
 The JavaScript tests may be run from a web browser or from the command line.
 
 Testing from a web browser
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To run the tests from a web browser, open up ``js_tests/tests.html`` in your
 browser.
@@ -119,7 +119,7 @@ over HTTP. To view code coverage:
 * Open http://localhost:8000/js_tests/tests.html in your web browser.
 
 Testing from the command line
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To run the tests from the command line, you need to have `Node.js`_ installed.
 

docs/internals/contributing/writing-code/submitting-patches.txt

@@ -7,7 +7,7 @@ with associated patches will get fixed *far* more quickly than those
 without patches.
 
 Typo fixes and trivial documentation changes
---------------------------------------------
+============================================
 
 If you are fixing a really trivial issue, for example changing a word in the
 documentation, the preferred way to provide the patch is using GitHub pull
@@ -16,7 +16,7 @@ requests without a Trac ticket.
 See the :doc:`working-with-git` for more details on how to use pull requests.
 
 "Claiming" tickets
-------------------
+==================
 
 In an open-source project with hundreds of contributors around the world, it's
 important to manage communication efficiently so that work doesn't get
@@ -62,7 +62,7 @@ and time availability), claim it by following these steps:
 .. _Contributor License Agreement: https://www.djangoproject.com/foundation/cla/
 
 Ticket claimers' responsibility
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Once you've claimed a ticket, you have a responsibility to work on that ticket
 in a reasonably timely fashion. If you don't have time to work on it, either
@@ -80,7 +80,7 @@ your claim on the ticket may be revoked.
 As always, more communication is better than less communication!
 
 Which tickets should be claimed?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 Of course, going through the steps of claiming tickets is overkill in some
 cases.
@@ -96,7 +96,7 @@ or not, to submit patches to a ticket if you happen to have a patch ready.
 .. _patch-style:
 
 Patch style
------------
+===========
 
 Make sure that any contribution you do fulfills at least the following
 requirements:
@@ -143,7 +143,7 @@ Regardless of the way you submit your work, follow these steps.
 .. _Development dashboard: https://dashboard.djangoproject.com/
 
 Non-trivial patches
--------------------
+===================
 
 A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
 that introduces Django functionality and makes some sort of design decision.
@@ -157,7 +157,7 @@ ask.
 .. _deprecating-a-feature:
 
 Deprecating a feature
----------------------
+=====================
 
 There are a couple reasons that code in Django might be deprecated:
 
@@ -233,7 +233,7 @@ In each :term:`feature release`, all ``RemovedInDjangoXXWarning``\s matching
 the new version are removed.
 
 JavaScript patches
-------------------
+==================
 
 For information on JavaScript patches, see the :ref:`javascript-patches`
 documentation.
@@ -241,7 +241,7 @@ documentation.
 .. _patch-review-checklist:
 
 Patch review checklist
-----------------------
+======================
 
 Use this checklist to review a pull request. If you are reviewing a pull
 request that is not your own and it passes all the criteria below, please set
@@ -260,7 +260,7 @@ Looking to get your patch reviewed? Ensure the Trac flags on the ticket are
 set so that the ticket appears in that queue.
 
 Documentation
-~~~~~~~~~~~~~
+-------------
 
 * Does the documentation build without any errors (``make html``, or
   ``make.bat html`` on Windows, from the ``docs`` directory)?
@@ -269,13 +269,13 @@ Documentation
 * Are there any :ref:`spelling errors <documentation-spelling-check>`?
 
 Bugs
-~~~~
+----
 
 * Is there a proper regression test (the test should fail before the fix
   is applied)?
 
 New Features
-~~~~~~~~~~~~
+------------
 
 * Are there tests to "exercise" all of the new code?
 * Is there a release note in ``docs/releases/A.B.txt``?
@@ -284,12 +284,12 @@ New Features
   ``.. versionadded:: A.B`` or ``.. versionchanged:: A.B``?
 
 Deprecating a feature
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 See the :ref:`deprecating-a-feature` guide.
 
 All code changes
-~~~~~~~~~~~~~~~~
+----------------
 
 * Does the :doc:`coding style
   </internals/contributing/writing-code/coding-style>` conform to our
@@ -300,7 +300,7 @@ All code changes
   to build the pull request against our continuous integration server.
 
 All tickets
-~~~~~~~~~~~
+-----------
 
 * Is the pull request a single squashed commit with a message that follows our
   :ref:`commit message format <committing-guidelines>`?

docs/internals/contributing/writing-code/unit-tests.txt

@@ -16,10 +16,10 @@ how to write new tests.
 .. _running-unit-tests:
 
 Running the unit tests
-----------------------
+======================
 
 Quickstart
-~~~~~~~~~~
+----------
 
 If you are on Python 2, you'll first need to install a backport of the
 ``unittest.mock`` module that's available in Python 3. See
@@ -48,7 +48,7 @@ Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
 .. _running-unit-tests-settings:
 
 Using another ``settings`` module
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 The included settings module allows you to run the test suite using
 SQLite. If you want to test behavior using a different database (and
@@ -92,7 +92,7 @@ test settings dictionary for the applicable database.
 .. _runtests-specifying-labels:
 
 Running only some of the tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Django's entire test suite takes a while to run, and running every single test
 could be redundant if, say, you just added a test to Django that you want to
@@ -119,7 +119,7 @@ Going beyond that, you can specify an individual test method like this::
    $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects
 
 Running the Selenium tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Some tests require Selenium and a Web browser (Firefox, Google Chrome, or
 Internet Explorer). To allow those tests to be run rather than skipped, you must
@@ -131,7 +131,7 @@ install the selenium_ package into your Python path and run the tests with the
 .. _running-unit-tests-dependencies:
 
 Running all the tests
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 If you want to run the full suite of tests, you'll need to install a number of
 dependencies:
@@ -188,7 +188,7 @@ associated tests will be skipped.
 .. _pip requirements files: https://pip.pypa.io/en/latest/user_guide.html#requirements-files
 
 Code coverage
-~~~~~~~~~~~~~
+-------------
 
 Contributors are encouraged to run coverage on the test suite to identify areas
 that need additional tests. The coverage tool installation and use is described
@@ -211,7 +211,7 @@ and also excludes several directories not relevant to the results
 .. _contrib-apps:
 
 Contrib apps
-------------
+============
 
 Tests for contrib apps can be found in the ``tests/`` directory, typically
 under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located
@@ -220,10 +220,10 @@ in ``tests/auth_tests``.
 .. _troubleshooting-unit-tests:
 
 Troubleshooting
----------------
+===============
 
 Many test failures with ``UnicodeEncodeError``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 If the ``locales`` package is not installed, some tests will fail with a
 ``UnicodeEncodeError``.
@@ -234,7 +234,7 @@ You can resolve this on Debian-based systems, for example, by running::
     $ dpkg-reconfigure locales
 
 Tests that only fail in combination
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 In case a test passes when run in isolation but fails within the whole suite,
 we have some tools to help analyze the problem.
@@ -279,7 +279,7 @@ cause any trouble::
     $ ./runtests.py basic --reverse
 
 Seeing the SQL queries run during a test
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 If you wish to examine the SQL being run in failing tests, you can turn on
 :ref:`SQL logging <django-db-logger>` using the ``--debug-sql`` option. If you
@@ -288,7 +288,7 @@ combine this with ``--verbosity=2``, all SQL queries will be output::
     $ ./runtests.py basic --debug-sql
 
 Seeing the full traceback of a test failure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 By default tests are run in parallel with one process per core. When the tests
 are run in parallel, however, you'll only see a truncated traceback for any

docs/internals/contributing/writing-code/working-with-git.txt

@@ -1,3 +1,4 @@
+===========================
 Working with Git and GitHub
 ===========================
 
@@ -14,7 +15,7 @@ You could also upload a traditional patch to Trac, but it's less practical for
 reviews.
 
 Installing Git
---------------
+==============
 
 Django uses `Git`_ for its source control. You can `download
 <http://git-scm.com/download>`_ Git, but it's often easier to install with
@@ -38,7 +39,7 @@ used to associate your commits with your GitHub account.
 .. _GitHub: https://github.com/
 
 Setting up local repository
----------------------------
+===========================
 
 When you have created your GitHub account, with the nick "GitHub_nick", and
 forked Django's repository, create a local copy of your fork::
@@ -64,7 +65,7 @@ You can add other remotes similarly, for example::
     git remote add akaariai git@github.com:akaariai/django.git
 
 Working on a ticket
--------------------
+===================
 
 When working on a ticket create a new branch for the work, and base that work
 on upstream/master::
@@ -94,7 +95,7 @@ necessary::
     git commit -m 'Added two more tests for edge cases'
 
 Publishing work
-~~~~~~~~~~~~~~~
+---------------
 
 You can publish your work on GitHub just by doing::
 
@@ -143,7 +144,7 @@ ready for merging -- or sufficiently close that a committer will finish it
 himself.
 
 Rebasing branches
-~~~~~~~~~~~~~~~~~
+-----------------
 
 In the example above you created two commits, the "Fixed ticket_xxxxx" commit
 and "Added two more tests" commit.
@@ -189,7 +190,7 @@ commit hashes do not match any more. This is acceptable, as the branch is merely
 a topic branch, and nobody should be basing their work on it.
 
 After upstream has changed
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 When upstream (django/django) has changed, you should rebase your work. To
 do this, use::
@@ -215,7 +216,7 @@ This way your branch will contain only commits related to its topic, which
 makes squashing easier.
 
 After review
-~~~~~~~~~~~~
+------------
 
 It is unusual to get any non-trivial amount of code into core without changes
 requested by reviewers. In this case, it is often a good idea to add the
@@ -247,7 +248,7 @@ Note that the committer is likely to squash the review commit into the previous
 commit when committing the code.
 
 Working on a patch
-------------------
+==================
 
 One of the ways that developers can contribute to Django is by reviewing
 patches. Those patches will typically exist as pull requests on GitHub and
@@ -264,7 +265,7 @@ For more detail on working with pull requests see the
 :ref:`guidelines for committers <handling-pull-requests>`.
 
 Summary
--------
+=======
 
 * Work on GitHub if you can.
 * Announce your work on the Trac ticket by linking to your GitHub branch.

docs/internals/contributing/writing-documentation.txt

@@ -19,7 +19,7 @@ This section explains how writers can craft their documentation changes
 in the most useful and least error-prone ways.
 
 Getting the raw documentation
------------------------------
+=============================
 
 Though Django's documentation is intended to be read as HTML at
 https://docs.djangoproject.com/, we edit it as a collection of text files for
@@ -36,7 +36,7 @@ to have the docs for the last release be up-to-date and correct (see
 :ref:`differences-between-doc-versions`).
 
 Getting started with Sphinx
----------------------------
+===========================
 
 Django's documentation uses the Sphinx__ documentation system, which in turn
 is based on docutils__. The basic idea is that lightly-formatted plain-text
@@ -66,7 +66,7 @@ Primer <sphinx:rst-primer>`. After that, you'll want to read about the
 metadata, indexing, and cross-references.
 
 How the documentation is organized
-----------------------------------
+==================================
 
 The documentation is organized into several categories:
 
@@ -117,7 +117,7 @@ The documentation is organized into several categories:
   repeat the same material.
 
 Writing style
--------------
+=============
 
 When using pronouns in reference to a hypothetical person, such as "a user with
 a session cookie", gender neutral pronouns (they/their/them) should be used.
@@ -130,7 +130,7 @@ Instead of:
 * himself or herself... use themselves.
 
 Commonly used terms
--------------------
+===================
 
 Here are some style guidelines on commonly used terms throughout the
 documentation:
@@ -160,7 +160,7 @@ documentation:
 * **website** -- use one word, without capitalization.
 
 Django-specific terminology
----------------------------
+===========================
 
 * **model** -- it's not capitalized.
 
@@ -172,7 +172,7 @@ Django-specific terminology
 * **view** -- it's not capitalized.
 
 Guidelines for reStructuredText files
--------------------------------------
+=====================================
 
 These guidelines regulate the format of our reST (reStructuredText)
 documentation:
@@ -199,8 +199,26 @@ documentation:
 * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
   documentation.
 
+* Use these heading styles::
+
+    ===
+    One
+    ===
+
+    Two
+    ===
+
+    Three
+    -----
+
+    Four
+    ~~~~
+
+    Five
+    ^^^^
+
 Django-specific markup
-----------------------
+======================
 
 Besides the `Sphinx built-in markup`__, Django's docs defines some extra
 description units:
@@ -251,7 +269,7 @@ __ http://sphinx-doc.org/markup/
 .. _documenting-new-features:
 
 Documenting new features
-------------------------
+========================
 
 Our policy for new features is:
 
@@ -309,7 +327,7 @@ We can simply remove the ``.. versionadded:: A.B`` annotation without any
 indentation changes when the time comes.
 
 Minimizing images
------------------
+=================
 
 Optimize image compression where possible. For PNG files, use OptiPNG and
 AdvanceCOMP's ``advpng``:
@@ -324,7 +342,7 @@ This is based on OptiPNG version 0.7.5. Older versions may complain about the
 ``--strip all`` option being lossy.
 
 An example
-----------
+==========
 
 For a quick example of how it all fits together, consider this hypothetical
 example:
@@ -377,7 +395,7 @@ example:
     .. setting:: ADMINS
 
     ADMINS
-    ------
+    ======
 
     Default: ``[]`` (Empty list)
 
@@ -400,7 +418,7 @@ That's basically how everything fits together.
 .. _improving-the-documentation:
 
 Improving the documentation
----------------------------
+===========================
 
 A few small improvements can be made to make the documentation read and
 look better:
@@ -451,7 +469,7 @@ look better:
 .. _documentation-spelling-check:
 
 Spelling check
---------------
+==============
 
 Before you commit your docs, it's a good idea to run the spelling checker.
 You'll need to install a couple packages first:
@@ -475,7 +493,7 @@ one of the following:
   to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
 
 Translating documentation
--------------------------
+=========================
 
 See :ref:`Localizing the Django documentation <translating-documentation>` if
 you'd like to help translate the documentation into another language.
@@ -483,7 +501,7 @@ you'd like to help translate the documentation into another language.
 .. _django-admin-manpage:
 
 ``django-admin`` man page
--------------------------
+=========================
 
 Sphinx can generate a manual page for the
 :doc:`django-admin </ref/django-admin>` command. This is configured in

docs/internals/index.txt

@@ -1,3 +1,4 @@
+================
 Django internals
 ================
 

docs/internals/mailing-lists.txt

@@ -16,7 +16,7 @@ anyone.
 .. _django-users-mailing-list:
 
 ``django-users``
-----------------
+================
 
 This is the right place if you are looking to ask any question regarding the
 installation, usage, or debugging of Django.
@@ -38,7 +38,7 @@ installation, usage, or debugging of Django.
 .. _django-core-mentorship-mailing-list:
 
 ``django-core-mentorship``
---------------------------
+==========================
 
 The Django Core Mentorship list is intended to provide a welcoming
 introductory environment for community members interested in contributing to
@@ -55,7 +55,7 @@ the Django Project.
 .. _django-developers-mailing-list:
 
 ``django-developers``
----------------------
+=====================
 
 The discussion about the development of Django itself takes place here.
 
@@ -76,7 +76,7 @@ The discussion about the development of Django itself takes place here.
 .. _django-i18n-mailing-list:
 
 ``django-i18n``
----------------
+===============
 
 This is the place to discuss the internationalization and localization of
 Django's components.
@@ -92,7 +92,7 @@ Django's components.
 .. _django-announce-mailing-list:
 
 ``django-announce``
--------------------
+===================
 
 A (very) low-traffic list for announcing new releases of Django and important
 bugfixes.
@@ -108,7 +108,7 @@ bugfixes.
 .. _django-updates-mailing-list:
 
 ``django-updates``
-------------------
+==================
 
 All the ticket updates are mailed automatically to this list, which is tracked
 by developers and interested community members.

docs/internals/security.txt

@@ -1,5 +1,3 @@
-.. _internals-security:
-
 ==========================
 Django's security policies
 ==========================

docs/intro/index.txt

@@ -1,3 +1,4 @@
+===============
 Getting started
 ===============
 

docs/intro/install.txt

@@ -1,3 +1,4 @@
+===================
 Quick install guide
 ===================
 
@@ -7,7 +8,7 @@ possibilities; this guide will guide you to a simple, minimal installation
 that'll work while you walk through the introduction.
 
 Install Python
---------------
+==============
 
 Being a Python Web framework, Django requires Python. See
 :ref:`faq-python-version-support` for details. Python includes a lightweight
@@ -34,21 +35,21 @@ you should see something like::
     >>>
 
 Set up a database
------------------
+=================
 
 This step is only necessary if you'd like to work with a "large" database engine
 like PostgreSQL, MySQL, or Oracle. To install such a database, consult the
 :ref:`database installation information <database-installation>`.
 
 Remove any old versions of Django
----------------------------------
+=================================
 
 If you are upgrading your installation of Django from a previous version, you
 will need to :ref:`uninstall the old Django version before installing the new
 version <removing-old-versions-of-django>`.
 
 Install Django
---------------
+==============
 
 You've got three easy options to install Django:
 
@@ -77,7 +78,7 @@ You've got three easy options to install Django:
 
 
 Verifying
----------
+=========
 
 To verify that Django can be seen by Python, type ``python`` from your shell.
 Then at the Python prompt, try to import Django:
@@ -91,6 +92,6 @@ Then at the Python prompt, try to import Django:
 You may have another version of Django installed.
 
 That's it!
-----------
+==========
 
 That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`.

docs/misc/index.txt

@@ -1,3 +1,4 @@
+=================================
 Meta-documentation and miscellany
 =================================
 

docs/ref/class-based-views/base.txt

@@ -14,7 +14,7 @@ ancestor classes are  documented under the section title of **Ancestors (MRO)**.
 MRO is an acronym for Method Resolution Order.
 
 View
-----
+====
 
 .. class:: django.views.generic.base.View
 
@@ -103,7 +103,7 @@ View
         list of the allowed HTTP method names for the view.
 
 TemplateView
-------------
+============
 
 .. class:: django.views.generic.base.TemplateView
 
@@ -155,7 +155,7 @@ TemplateView
       the keyword arguments captured from the URL pattern that served the view.
 
 RedirectView
-------------
+============
 
 .. class:: django.views.generic.base.RedirectView
 

docs/ref/class-based-views/flattened-index.txt

@@ -9,10 +9,10 @@ documentation organized by the class which defines the behavior, see
 :doc:`Class-based views</ref/class-based-views/index>`
 
 Simple generic views
---------------------
+====================
 
 View
-~~~~
+----
 .. class:: View()
 
 **Attributes** (with optional accessor):
@@ -27,7 +27,7 @@ View
 * :meth:`~django.views.generic.base.View.http_method_not_allowed`
 
 TemplateView
-~~~~~~~~~~~~
+------------
 .. class:: TemplateView()
 
 **Attributes** (with optional accessor):
@@ -49,7 +49,7 @@ TemplateView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 RedirectView
-~~~~~~~~~~~~
+------------
 .. class:: RedirectView()
 
 **Attributes** (with optional accessor):
@@ -73,10 +73,10 @@ RedirectView
 * ``put()``
 
 Detail Views
-------------
+============
 
 DetailView
-~~~~~~~~~~
+----------
 .. class:: DetailView()
 
 **Attributes** (with optional accessor):
@@ -107,10 +107,10 @@ DetailView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 List Views
-----------
+==========
 
 ListView
-~~~~~~~~
+--------
 .. class:: ListView()
 
 **Attributes** (with optional accessor):
@@ -143,10 +143,10 @@ ListView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 Editing views
--------------
+=============
 
 FormView
-~~~~~~~~
+--------
 .. class:: FormView()
 
 **Attributes** (with optional accessor):
@@ -176,7 +176,7 @@ FormView
 * :meth:`~django.views.generic.edit.ProcessFormView.put`
 
 CreateView
-~~~~~~~~~~
+----------
 .. class:: CreateView()
 
 **Attributes** (with optional accessor):
@@ -218,7 +218,7 @@ CreateView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 UpdateView
-~~~~~~~~~~
+----------
 .. class:: UpdateView()
 
 **Attributes** (with optional accessor):
@@ -260,7 +260,7 @@ UpdateView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 DeleteView
-~~~~~~~~~~
+----------
 .. class:: DeleteView()
 
 **Attributes** (with optional accessor):
@@ -294,10 +294,10 @@ DeleteView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 Date-based views
-----------------
+================
 
 ArchiveIndexView
-~~~~~~~~~~~~~~~~
+----------------
 .. class:: ArchiveIndexView()
 
 **Attributes** (with optional accessor):
@@ -335,7 +335,7 @@ ArchiveIndexView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 YearArchiveView
-~~~~~~~~~~~~~~~
+---------------
 .. class:: YearArchiveView()
 
 **Attributes** (with optional accessor):
@@ -376,7 +376,7 @@ YearArchiveView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 MonthArchiveView
-~~~~~~~~~~~~~~~~
+----------------
 .. class:: MonthArchiveView()
 
 **Attributes** (with optional accessor):
@@ -420,7 +420,7 @@ MonthArchiveView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 WeekArchiveView
-~~~~~~~~~~~~~~~
+---------------
 .. class:: WeekArchiveView()
 
 **Attributes** (with optional accessor):
@@ -462,7 +462,7 @@ WeekArchiveView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 DayArchiveView
-~~~~~~~~~~~~~~
+--------------
 .. class:: DayArchiveView()
 
 **Attributes** (with optional accessor):
@@ -510,7 +510,7 @@ DayArchiveView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 TodayArchiveView
-~~~~~~~~~~~~~~~~
+----------------
 .. class:: TodayArchiveView()
 
 **Attributes** (with optional accessor):
@@ -558,7 +558,7 @@ TodayArchiveView
 * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
 
 DateDetailView
-~~~~~~~~~~~~~~
+--------------
 .. class:: DateDetailView()
 
 **Attributes** (with optional accessor):

docs/ref/class-based-views/generic-date-based.txt

@@ -23,7 +23,7 @@ views for displaying drilldown pages for date-based data.
                 return reverse('article-detail', kwargs={'pk': self.pk})
 
 ArchiveIndexView
-----------------
+================
 
 .. class:: ArchiveIndexView
 
@@ -87,7 +87,7 @@ ArchiveIndexView
     This will output all articles.
 
 YearArchiveView
----------------
+===============
 
 .. class:: YearArchiveView
 
@@ -192,7 +192,7 @@ YearArchiveView
         </div>
 
 MonthArchiveView
-----------------
+================
 
 .. class:: MonthArchiveView
 
@@ -289,7 +289,7 @@ MonthArchiveView
         </p>
 
 WeekArchiveView
----------------
+===============
 
 .. class:: WeekArchiveView
 
@@ -392,7 +392,7 @@ WeekArchiveView
     filter ``'%U'`` outputs the number of seconds since the Unix epoch.
 
 DayArchiveView
---------------
+==============
 
 .. class:: DayArchiveView
 
@@ -494,7 +494,7 @@ DayArchiveView
         </p>
 
 TodayArchiveView
-----------------
+================
 
 .. class:: TodayArchiveView
 
@@ -551,7 +551,7 @@ TodayArchiveView
         name of the new template.
 
 DateDetailView
---------------
+==============
 
 .. class:: DateDetailView
 

docs/ref/class-based-views/generic-display.txt

@@ -6,7 +6,7 @@ The two following generic class-based views are designed to display data. On
 many projects they are typically the most commonly used views.
 
 DetailView
-----------
+==========
 
 .. class:: django.views.generic.detail.DetailView
 
@@ -73,7 +73,7 @@ DetailView
         <p>Date: {{ now|date }}</p>
 
 ListView
---------
+========
 
 .. class:: django.views.generic.list.ListView
 

docs/ref/class-based-views/generic-editing.txt

@@ -25,7 +25,7 @@ editing content:
                 return reverse('author-detail', kwargs={'pk': self.pk})
 
 FormView
---------
+========
 
 .. class:: django.views.generic.edit.FormView
 
@@ -81,7 +81,7 @@ FormView
 
 
 CreateView
-----------
+==========
 
 .. class:: django.views.generic.edit.CreateView
 
@@ -136,7 +136,7 @@ CreateView
         </form>
 
 UpdateView
-----------
+==========
 
 .. class:: django.views.generic.edit.UpdateView
 
@@ -193,7 +193,7 @@ UpdateView
         </form>
 
 DeleteView
-----------
+==========
 
 .. class:: django.views.generic.edit.DeleteView
 

docs/ref/class-based-views/index.txt

@@ -16,7 +16,7 @@ Class-based views API reference. For introductory material, see the
    flattened-index
 
 Specification
--------------
+=============
 
 Each request served by a class-based view has an independent state; therefore,
 it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
@@ -44,7 +44,7 @@ previous example, this means that every request on ``MyView`` is able to use
 the class (return ``True`` on a ``hasattr`` check).
 
 Base vs Generic views
----------------------
+=====================
 
 Base class-based views can be thought of as *parent* views, which can be
 used by themselves or inherited from. They may not provide all the

docs/ref/class-based-views/mixins-date-based.txt

@@ -11,7 +11,7 @@ Date-based mixins
     characters from the :ttag:`now` template tag as they are not compatible.
 
 YearMixin
----------
+=========
 
 .. class:: YearMixin
 
@@ -63,7 +63,7 @@ YearMixin
         :attr:`~DateMixin.allow_future`.
 
 MonthMixin
-----------
+==========
 
 .. class:: MonthMixin
 
@@ -115,7 +115,7 @@ MonthMixin
         :attr:`~DateMixin.allow_future`.
 
 DayMixin
---------
+========
 
 .. class:: DayMixin
 
@@ -167,7 +167,7 @@ DayMixin
         :attr:`~DateMixin.allow_future`.
 
 WeekMixin
----------
+=========
 
 .. class:: WeekMixin
 
@@ -220,7 +220,7 @@ WeekMixin
         :attr:`~DateMixin.allow_future`.
 
 DateMixin
----------
+=========
 
 .. class:: DateMixin
 
@@ -266,7 +266,7 @@ DateMixin
         :attr:`~DateMixin.allow_future` by default.
 
 BaseDateListView
-----------------
+================
 
 .. class:: BaseDateListView
 

docs/ref/class-based-views/mixins-editing.txt

@@ -15,7 +15,7 @@ The following mixins are used to construct Django's editing views:
     the documentation on :doc:`/ref/class-based-views/generic-editing`.
 
 FormMixin
----------
+=========
 
 .. class:: django.views.generic.edit.FormMixin
 
@@ -95,7 +95,7 @@ FormMixin
         name 'form'.
 
 ModelFormMixin
---------------
+==============
 
 .. class:: django.views.generic.edit.ModelFormMixin
 
@@ -181,7 +181,7 @@ ModelFormMixin
 
 
 ProcessFormView
----------------
+===============
 
 .. class:: django.views.generic.edit.ProcessFormView
 
@@ -221,7 +221,7 @@ ProcessFormView
 
 
 DeletionMixin
--------------
+=============
 
 .. class:: django.views.generic.edit.DeletionMixin
 

docs/ref/class-based-views/mixins-multiple-object.txt

@@ -3,7 +3,7 @@ Multiple object mixins
 ======================
 
 MultipleObjectMixin
--------------------
+===================
 
 .. class:: django.views.generic.list.MultipleObjectMixin
 
@@ -193,7 +193,7 @@ MultipleObjectMixin
 
 
 MultipleObjectTemplateResponseMixin
------------------------------------
+===================================
 
 .. class:: django.views.generic.list.MultipleObjectTemplateResponseMixin
 

docs/ref/class-based-views/mixins-simple.txt

@@ -3,7 +3,7 @@ Simple mixins
 =============
 
 ContextMixin
-------------
+============
 
 .. class:: django.views.generic.base.ContextMixin
 
@@ -32,7 +32,7 @@ ContextMixin
             <alters-data-description>`.
 
 TemplateResponseMixin
----------------------
+=====================
 
 .. class:: django.views.generic.base.TemplateResponseMixin
 

docs/ref/class-based-views/mixins-single-object.txt

@@ -3,7 +3,7 @@ Single object mixins
 ====================
 
 SingleObjectMixin
------------------
+=================
 
 .. class:: django.views.generic.detail.SingleObjectMixin
 
@@ -132,7 +132,7 @@ SingleObjectMixin
 
 
 SingleObjectTemplateResponseMixin
----------------------------------
+=================================
 
 .. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin
 

docs/ref/clickjacking.txt

@@ -52,7 +52,7 @@ How to use it
 =============
 
 Setting X-Frame-Options for all responses
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 To set the same ``X-Frame-Options`` value for all responses in your site, put
 ``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to
@@ -86,7 +86,7 @@ that tells the middleware not to set the header::
 
 
 Setting X-Frame-Options per view
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 To set the ``X-Frame-Options`` header on a per view basis, Django provides these
 decorators::
@@ -114,7 +114,7 @@ modern browser. Older browsers will quietly ignore the header and need `other
 clickjacking prevention techniques`_.
 
 Browsers that support X-Frame-Options
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 * Internet Explorer 8+
 * Firefox 3.6.9+
@@ -123,7 +123,7 @@ Browsers that support X-Frame-Options
 * Chrome 4.1+
 
 See also
-~~~~~~~~
+--------
 
 A `complete list`_ of browsers supporting ``X-Frame-Options``.
 

docs/ref/contrib/auth.txt

@@ -1,3 +1,4 @@
+=======================
 ``django.contrib.auth``
 =======================
 

docs/ref/contrib/gis/forms-api.txt

@@ -18,7 +18,7 @@ In addition to the regular :ref:`form field arguments <core-field-arguments>`,
 GeoDjango form fields take the following optional arguments.
 
 ``srid``
-~~~~~~~~
+--------
 
 .. attribute:: Field.srid
 
@@ -28,7 +28,7 @@ GeoDjango form fields take the following optional arguments.
     input values into that SRID.
 
 ``geom_type``
-~~~~~~~~~~~~~
+-------------
 
 .. attribute:: Field.geom_type
 
@@ -40,42 +40,42 @@ Form field classes
 ==================
 
 ``GeometryField``
-~~~~~~~~~~~~~~~~~
+-----------------
 
 .. class:: GeometryField
 
 ``PointField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: PointField
 
 ``LineStringField``
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. class:: LineStringField
 
 ``PolygonField``
-~~~~~~~~~~~~~~~~
+----------------
 
 .. class:: PolygonField
 
 ``MultiPointField``
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. class:: MultiPointField
 
 ``MultiLineStringField``
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 .. class:: MultiLineStringField
 
 ``MultiPolygonField``
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 .. class:: MultiPolygonField
 
 ``GeometryCollectionField``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 .. class:: GeometryCollectionField
 
@@ -91,7 +91,7 @@ Note that none of the currently available widgets supports 3D geometries, hence
 geometry fields will fallback using a simple ``Textarea`` widget for such data.
 
 Widget attributes
-~~~~~~~~~~~~~~~~~
+-----------------
 
 GeoDjango widgets are template-based, so their attributes are mostly different
 from other Django widget attributes.
@@ -134,7 +134,7 @@ widget. For example::
             forms.OSMWidget(attrs={'map_width': 800, 'map_height': 500}))
 
 Widget classes
-~~~~~~~~~~~~~~
+--------------
 
 ``BaseGeometryWidget``
 

docs/ref/contrib/gis/functions.txt

@@ -36,7 +36,7 @@ Measurement         Relationships             Operations              Editors
 ==================  =======================   ======================  ===================  ==================  =====================
 
 Area
-----
+====
 
 .. class:: Area(expression, **extra)
 
@@ -48,7 +48,7 @@ float value is returned, as it's not possible to automatically determine the
 unit of the field.
 
 AsGeoJSON
----------
+=========
 
 .. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
 
@@ -80,7 +80,7 @@ Keyword Argument       Description
 =====================  =====================================================
 
 AsGML
------
+=====
 
 .. class:: AsGML(expression, version=2, precision=8, **extra)
 
@@ -111,7 +111,7 @@ Keyword Argument       Description
 __ https://en.wikipedia.org/wiki/Geography_Markup_Language
 
 AsKML
------
+=====
 
 .. class:: AsKML(expression, precision=8, **extra)
 
@@ -138,7 +138,7 @@ Keyword Argument       Description
 __ https://developers.google.com/kml/documentation/
 
 AsSVG
------
+=====
 
 .. class:: AsSVG(expression, relative=False, precision=8, **extra)
 
@@ -162,7 +162,7 @@ Keyword Argument       Description
 __ http://www.w3.org/Graphics/SVG/
 
 BoundingCircle
---------------
+==============
 
 .. class:: BoundingCircle(expression, num_seg=48, **extra)
 
@@ -172,7 +172,7 @@ Accepts a single geographic field or expression and returns the smallest circle
 polygon that can fully contain the geometry.
 
 Centroid
---------
+========
 
 .. class:: Centroid(expression, **extra)
 
@@ -182,7 +182,7 @@ Accepts a single geographic field or expression and returns the ``centroid``
 value of the geometry.
 
 Difference
-----------
+==========
 
 .. class:: Difference(expr1, expr2, **extra)
 
@@ -197,7 +197,7 @@ geometry B.
     MySQL support was added.
 
 Distance
---------
+========
 
 .. class:: Distance(expr1, expr2, spheroid=None, **extra)
 
@@ -241,7 +241,7 @@ queryset is calculated::
     :ref:`supported_units`.
 
 Envelope
---------
+========
 
 .. class:: Envelope(expression, **extra)
 
@@ -251,7 +251,7 @@ Accepts a single geographic field or expression and returns the geometry
 representing the bounding box of the geometry.
 
 ForceRHR
---------
+========
 
 .. class:: ForceRHR(expression, **extra)
 
@@ -262,7 +262,7 @@ of the polygon/multipolygon in which all of the vertices follow the
 right-hand rule.
 
 GeoHash
--------
+=======
 
 .. class:: GeoHash(expression, **extra)
 
@@ -278,7 +278,7 @@ representation of the geometry.
 __ https://en.wikipedia.org/wiki/Geohash
 
 Intersection
-------------
+============
 
 .. class:: Intersection(expr1, expr2, **extra)
 
@@ -292,7 +292,7 @@ intersection between them.
     MySQL support was added.
 
 Length
-------
+======
 
 .. class:: Length(expression, spheroid=True, **extra)
 
@@ -309,7 +309,7 @@ accurate, less resource-intensive) or on a spheroid (more accurate, more
 resource-intensive) with the ``spheroid`` keyword argument.
 
 MemSize
--------
+=======
 
 .. class:: MemSize(expression, **extra)
 
@@ -319,7 +319,7 @@ Accepts a single geographic field or expression and returns the memory size
 (number of bytes) that the geometry field takes.
 
 NumGeometries
--------------
+=============
 
 .. class:: NumGeometries(expression, **extra)
 
@@ -330,7 +330,7 @@ geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION``
 or ``MULTI*`` field); otherwise returns ``None``.
 
 NumPoints
----------
+=========
 
 .. class:: NumPoints(expression, **extra)
 
@@ -340,7 +340,7 @@ Accepts a single geographic field or expression and returns the number of points
 in the first linestring in the geometry field; otherwise returns ``None``.
 
 Perimeter
----------
+=========
 
 .. class:: Perimeter(expression, **extra)
 
@@ -352,7 +352,7 @@ MySQL, a raw float value is returned, as it's not possible to automatically
 determine the unit of the field.
 
 PointOnSurface
---------------
+==============
 
 .. class:: PointOnSurface(expression, **extra)
 
@@ -362,7 +362,7 @@ Accepts a single geographic field or expression and returns a ``Point`` geometry
 guaranteed to lie on the surface of the field; otherwise returns ``None``.
 
 Reverse
--------
+=======
 
 .. class:: Reverse(expression, **extra)
 
@@ -372,7 +372,7 @@ Accepts a single geographic field or expression and returns a geometry with
 reversed coordinates.
 
 Scale
------
+=====
 
 .. class:: Scale(expression, x, y, z=0.0, **extra)
 
@@ -383,7 +383,7 @@ scaled coordinates by multiplying them with the ``x``, ``y``, and optionally
 ``z`` parameters.
 
 SnapToGrid
-----------
+==========
 
 .. class:: SnapToGrid(expression, *args, **extra)
 
@@ -403,7 +403,7 @@ Number of Arguments  Description
 ===================  =====================================================
 
 SymDifference
--------------
+=============
 
 .. class:: SymDifference(expr1, expr2, **extra)
 
@@ -418,7 +418,7 @@ parameters.
     MySQL support was added.
 
 Transform
----------
+=========
 
 .. class:: Transform(expression, srid, **extra)
 
@@ -435,7 +435,7 @@ the transformed geometry to the spatial reference system specified by the
     are not necessarily the same as those used by PostGIS.
 
 Translate
----------
+=========
 
 .. class:: Translate(expression, x, y, z=0.0, **extra)
 
@@ -446,7 +446,7 @@ its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric
 parameters.
 
 Union
------
+=====
 
 .. class:: Union(expr1, expr2, **extra)
 

docs/ref/contrib/gis/install/geolibs.txt

@@ -120,10 +120,10 @@ script, compile, and install::
     $ cd ..
 
 Troubleshooting
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 Can't find GEOS library
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 When GeoDjango can't find GEOS, this error is raised:
 
@@ -139,7 +139,7 @@ If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binut
 .. _geoslibrarypath:
 
 ``GEOS_LIBRARY_PATH``
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 If your GEOS library is in a non-standard location, or you don't want to
 modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
@@ -222,10 +222,10 @@ __ https://trac.osgeo.org/gdal/wiki/GdalOgrInPython
 .. _gdaltrouble:
 
 Troubleshooting
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 Can't find GDAL library
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
 will be false:
@@ -242,7 +242,7 @@ The solution is to properly configure your :ref:`libsettings` *or* set
 .. _gdallibrarypath:
 
 ``GDAL_LIBRARY_PATH``
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 If your GDAL library is in a non-standard location, or you don't want to
 modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`

docs/ref/contrib/gis/install/index.txt

@@ -129,7 +129,7 @@ an environment variable, or by configuring the library path for the entire
 system.
 
 ``LD_LIBRARY_PATH`` environment variable
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A user may set this environment variable to customize the library paths
 they want to use.  The typical library directory for software
@@ -140,7 +140,7 @@ could place the following in their bash profile::
     export LD_LIBRARY_PATH=/usr/local/lib
 
 Setting system library path
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
 additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
@@ -160,7 +160,7 @@ modifying the system library path::
 .. _binutils:
 
 Install ``binutils``
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
 module) to discover libraries.  The ``find_library`` routine uses a program
@@ -203,7 +203,7 @@ Foundation, however, this is not required.
 .. _macosx_python:
 
 Python
-^^^^^^
+~~~~~~
 
 Although OS X comes with Python installed, users can use `framework
 installers`__ provided by the Python Software Foundation.  An advantage to
@@ -223,7 +223,7 @@ __ https://www.python.org/ftp/python/
 .. _postgresapp:
 
 Postgres.app
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 `Postgres.app <http://postgresapp.com/>`_ is a standalone PostgreSQL server
 that includes the PostGIS extension. You will also need to install ``gdal`` and
@@ -243,7 +243,7 @@ terminal prompt.
 .. _homebrew:
 
 Homebrew
-^^^^^^^^
+~~~~~~~~
 
 `Homebrew`__ provides "recipes" for building binaries and packages from source.
 It provides recipes for the GeoDjango prerequisites on Macintosh computers
@@ -263,7 +263,7 @@ __ http://brew.sh/
 .. _kyngchaos:
 
 KyngChaos packages
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 William Kyngesburye provides a number of `geospatial library binary packages`__
 that make it simple to get GeoDjango installed on OS X without compiling
@@ -306,7 +306,7 @@ __ http://www.kyngchaos.com/software/postgres
 .. _psycopg2_kyngchaos:
 
 psycopg2
-~~~~~~~~
+^^^^^^^^
 
 After you've installed the KyngChaos binaries and modified your ``PATH``, as
 described above, ``psycopg2`` may be installed using the following command::
@@ -334,7 +334,7 @@ __ http://pdb.finkproject.org/pdb/browse.php?summary=django-gis
 .. _macports:
 
 MacPorts
-^^^^^^^^
+~~~~~~~~
 
 `MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
 computers running OS X.  Because MacPorts still builds the software from source,
@@ -379,7 +379,7 @@ GeoDjango on Windows.
     GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
 
 Python
-^^^^^^
+~~~~~~
 
 First, download the latest `Python 2.7 installer`__ from the Python website.
 Next, run the installer and keep the defaults -- for example, keep
@@ -395,7 +395,7 @@ Next, run the installer and keep the defaults -- for example, keep
 __ https://python.org/download/
 
 PostgreSQL
-^^^^^^^^^^
+~~~~~~~~~~
 
 First, download the latest `PostgreSQL 9.x installer`__ from the
 `EnterpriseDB`__ website.  After downloading, simply run the installer,
@@ -427,7 +427,7 @@ __ http://www.enterprisedb.com
 .. _postgisasb:
 
 PostGIS
-^^^^^^^
+~~~~~~~
 
 From within the Application Stack Builder (to run outside of the installer,
 :menuselection:`Start --> Programs --> PostgreSQL 9.x`), select
@@ -446,7 +446,7 @@ default PostGIS database).
     password in the 'Database Connection Information' dialog.
 
 psycopg2
-^^^^^^^^
+~~~~~~~~
 
 The ``psycopg2`` Python module provides the interface between Python and the
 PostgreSQL database.  Download the latest `Windows installer`__ for your version
@@ -457,7 +457,7 @@ __ http://www.stickpeople.com/projects/python/win-psycopg/
 .. _osgeo4w:
 
 OSGeo4W
-^^^^^^^
+~~~~~~~
 
 The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
 libraries required by GeoDjango.  First, download the `OSGeo4W installer`_,
@@ -471,7 +471,7 @@ installer.
 .. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/
 
 Modify Windows environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to use GeoDjango, you will need to add your Python and OSGeo4W
 directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
@@ -506,7 +506,7 @@ script, :download:`geodjango_setup.bat`.
     variables accordingly.
 
 Install Django and set up database
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Finally, :ref:`install Django <installing-official-release>` on your system.
 

docs/ref/contrib/gis/install/spatialite.txt

@@ -20,13 +20,13 @@ __ http://www.gaia-gis.it/gaia-sins/
 .. _spatialite_source:
 
 Installing from source
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 :doc:`GEOS and PROJ.4</ref/contrib/gis/install/geolibs>` should be installed
 prior to building SpatiaLite.
 
 SQLite
-^^^^^^
+------
 
 Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3
 command line interface and enter the following query::
@@ -57,7 +57,7 @@ __ https://www.sqlite.org/download.html
 .. _spatialitebuild:
 
 SpatiaLite library (``libspatialite``)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------
 
 Get the latest SpatiaLite library source bundle from the
 `download page`__::
@@ -81,13 +81,13 @@ __ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
 .. _spatialite_macosx:
 
 Mac OS X-specific instructions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==============================
 
 To install the SpatiaLite library and tools, Mac OS X users can choose between
 :ref:`kyngchaos` and `Homebrew`_.
 
 KyngChaos
-^^^^^^^^^
+---------
 
 First, follow the instructions in the :ref:`kyngchaos` section.
 
@@ -109,7 +109,7 @@ add the following to your ``settings.py``::
 __ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
 
 Homebrew
-^^^^^^^^
+--------
 
 `Homebrew`_ handles all the SpatiaLite related packages on your behalf,
 including SQLite3, SpatiaLite, PROJ, and GEOS. Install them like this::
@@ -128,7 +128,7 @@ following to your ``settings.py``::
 .. _create_spatialite_db:
 
 Creating a spatial database for SpatiaLite
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================================
 
 When running ``manage.py migrate`` with a SQLite or SpatiaLite database, the
 database file will be automatically created if it doesn't exist. Django will

docs/ref/contrib/gis/model-api.txt

@@ -104,7 +104,7 @@ __ https://en.wikipedia.org/wiki/WGS84
 .. _selecting-an-srid:
 
 Selecting an SRID
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 Choosing an appropriate SRID for your model is an important decision that the
 developer should consider carefully.  The SRID is an integer specifier that
@@ -213,7 +213,7 @@ details.
 .. _geography-type:
 
 Geography Type
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 The geography type provides native support for spatial features represented
 with geographic coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_

docs/ref/contrib/gis/testing.txt

@@ -20,7 +20,7 @@ Settings
 .. setting:: POSTGIS_VERSION
 
 ``POSTGIS_VERSION``
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 When GeoDjango's spatial backend initializes on PostGIS, it has to perform
 an SQL query to determine the version in order to figure out what
@@ -43,7 +43,7 @@ only needs to have the ability to create databases. In other configurations,
 you may be required to use a database superuser.
 
 Create database user
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 To make a database user with the ability to create databases, use the
 following command::
@@ -59,7 +59,7 @@ Alternatively, you may alter an existing user's role from the SQL shell
     postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
 
 Create database superuser
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This may be done at the time the user is created, for example::
 

docs/ref/contrib/gis/tutorial.txt

@@ -695,7 +695,7 @@ GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>`
 with support for editing geometry fields.
 
 Basics
-^^^^^^
+~~~~~~
 
 GeoDjango also supplements the Django admin by allowing users to create
 and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_).
@@ -742,7 +742,7 @@ position.
 .. _osmgeoadmin-intro:
 
 ``OSMGeoAdmin``
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses
 a `Open Street Map`_ layer in the admin.

docs/ref/contrib/humanize.txt

@@ -16,7 +16,7 @@ filters.
 .. templatefilter:: apnumber
 
 apnumber
---------
+========
 
 For numbers 1-9, returns the number spelled out. Otherwise, returns the
 number. This follows Associated Press style.
@@ -32,7 +32,7 @@ You can pass in either an integer or a string representation of an integer.
 .. templatefilter:: intcomma
 
 intcomma
---------
+========
 
 Converts an integer to a string containing commas every three digits.
 
@@ -43,7 +43,7 @@ Examples:
 * ``450000`` becomes ``450,000``.
 * ``4500000`` becomes ``4,500,000``.
 
-:ref:`Format localization <format-localization>` will be respected if enabled,
+:doc:`/topics/i18n/formatting` will be respected if enabled,
 e.g. with the ``'de'`` language:
 
 * ``45000`` becomes ``'45.000'``.
@@ -54,7 +54,7 @@ You can pass in either an integer or a string representation of an integer.
 .. templatefilter:: intword
 
 intword
--------
+=======
 
 Converts a large integer to a friendly text representation. Works best for
 numbers over 1 million.
@@ -67,7 +67,7 @@ Examples:
 
 Values up to 10^100 (Googol) are supported.
 
-:ref:`Format localization <format-localization>` will be respected if enabled,
+:doc:`/topics/i18n/formatting` will be respected if enabled,
 e.g. with the ``'de'`` language:
 
 * ``1000000`` becomes ``'1,0 Million'``.
@@ -79,7 +79,7 @@ You can pass in either an integer or a string representation of an integer.
 .. templatefilter:: naturalday
 
 naturalday
-----------
+==========
 
 For dates that are the current day or within one day, return "today",
 "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
@@ -98,7 +98,7 @@ Examples (when 'today' is 17 Feb 2007):
 .. templatefilter:: naturaltime
 
 naturaltime
------------
+===========
 
 For datetime values, returns a string representing how many seconds,
 minutes or hours ago it was -- falling back to the :tfilter:`timesince`
@@ -130,7 +130,7 @@ Examples (when 'now' is 17 Feb 2007 16:30:00):
 .. templatefilter:: ordinal
 
 ordinal
--------
+=======
 
 Converts an integer to its ordinal as a string.
 

docs/ref/contrib/postgres/aggregates.txt

@@ -19,17 +19,17 @@ These functions are described in more detail in the `PostgreSQL docs
         {'arr': [0, 1, 2]}
 
 General-purpose aggregation functions
--------------------------------------
+=====================================
 
 ArrayAgg
-~~~~~~~~
+--------
 
 .. class:: ArrayAgg(expression, **extra)
 
     Returns a list of values, including nulls, concatenated into an array.
 
 BitAnd
-~~~~~~
+------
 
 .. class:: BitAnd(expression, **extra)
 
@@ -37,7 +37,7 @@ BitAnd
     ``None`` if all values are null.
 
 BitOr
-~~~~~
+-----
 
 .. class:: BitOr(expression, **extra)
 
@@ -45,7 +45,7 @@ BitOr
     ``None`` if all values are null.
 
 BoolAnd
-~~~~~~~~
+-------
 
 .. class:: BoolAnd(expression, **extra)
 
@@ -53,7 +53,7 @@ BoolAnd
     null or if there are no values, otherwise ``False`` .
 
 BoolOr
-~~~~~~
+------
 
 .. class:: BoolOr(expression, **extra)
 
@@ -61,7 +61,7 @@ BoolOr
     values are null or if there are no values, otherwise ``False``.
 
 StringAgg
-~~~~~~~~~
+---------
 
 .. class:: StringAgg(expression, delimiter)
 
@@ -73,16 +73,16 @@ StringAgg
         Required argument. Needs to be a string.
 
 Aggregate functions for statistics
-----------------------------------
+==================================
 
 ``y`` and ``x``
-~~~~~~~~~~~~~~~
+---------------
 
 The arguments ``y`` and ``x`` for all these functions can be the name of a
 field or an expression returning a numeric data. Both are required.
 
 Corr
-~~~~
+----
 
 .. class:: Corr(y, x)
 
@@ -90,7 +90,7 @@ Corr
     aren't any matching rows.
 
 CovarPop
-~~~~~~~~
+--------
 
 .. class:: CovarPop(y, x, sample=False)
 
@@ -106,7 +106,7 @@ CovarPop
         population covariance.
 
 RegrAvgX
-~~~~~~~~
+--------
 
 .. class:: RegrAvgX(y, x)
 
@@ -114,7 +114,7 @@ RegrAvgX
     ``float``, or ``None`` if there aren't any matching rows.
 
 RegrAvgY
-~~~~~~~~
+--------
 
 .. class:: RegrAvgY(y, x)
 
@@ -122,7 +122,7 @@ RegrAvgY
     ``float``, or ``None`` if there aren't any matching rows.
 
 RegrCount
-~~~~~~~~~
+---------
 
 .. class:: RegrCount(y, x)
 
@@ -130,7 +130,7 @@ RegrCount
     are not null.
 
 RegrIntercept
-~~~~~~~~~~~~~
+-------------
 
 .. class:: RegrIntercept(y, x)
 
@@ -139,7 +139,7 @@ RegrIntercept
     matching rows.
 
 RegrR2
-~~~~~~
+------
 
 .. class:: RegrR2(y, x)
 
@@ -147,7 +147,7 @@ RegrR2
     ``None`` if there aren't any matching rows.
 
 RegrSlope
-~~~~~~~~~
+---------
 
 .. class:: RegrSlope(y, x)
 
@@ -156,7 +156,7 @@ RegrSlope
     matching rows.
 
 RegrSXX
-~~~~~~~
+-------
 
 .. class:: RegrSXX(y, x)
 
@@ -164,7 +164,7 @@ RegrSXX
     variable) as a ``float``, or ``None`` if there aren't any matching rows.
 
 RegrSXY
-~~~~~~~
+-------
 
 .. class:: RegrSXY(y, x)
 
@@ -173,7 +173,7 @@ RegrSXY
     matching rows.
 
 RegrSYY
-~~~~~~~
+-------
 
 .. class:: RegrSYY(y, x)
 
@@ -181,7 +181,7 @@ RegrSYY
     variable)  as a ``float``, or ``None`` if there aren't any matching rows.
 
 Usage examples
---------------
+==============
 
 We will use this example table::
 

docs/ref/contrib/postgres/fields.txt

@@ -1,3 +1,4 @@
+================================
 PostgreSQL specific model fields
 ================================
 
@@ -7,7 +8,7 @@ module.
 .. currentmodule:: django.contrib.postgres.fields
 
 ArrayField
-----------
+==========
 
 .. class:: ArrayField(base_field, size=None, **options)
 
@@ -91,7 +92,7 @@ ArrayField
     nullable and the values padded with ``None``.
 
 Querying ArrayField
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 There are a number of custom lookups and transforms for :class:`ArrayField`.
 We will use the following example model::
@@ -242,7 +243,7 @@ lookups available after the transform do not change. For example::
     fashion by Django.
 
 Indexing ArrayField
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 At present using :attr:`~django.db.models.Field.db_index` will create a
 ``btree`` index. This does not offer particularly significant help to querying.
@@ -250,7 +251,7 @@ A more useful index is a ``GIN`` index, which you should create using a
 :class:`~django.db.migrations.operations.RunSQL` operation.
 
 HStoreField
------------
+===========
 
 .. class:: HStoreField(**options)
 
@@ -292,7 +293,7 @@ HStoreField
     :class:`~django.contrib.postgres.validators.KeysValidator`.
 
 Querying HStoreField
-^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 In addition to the ability to query by key, there are a number of custom
 lookups available for ``HStoreField``.
@@ -457,7 +458,7 @@ using in conjunction with lookups on
     <QuerySet [<Dog: Meg>]>
 
 JSONField
----------
+=========
 
 .. versionadded:: 1.9
 
@@ -492,7 +493,7 @@ JSONField
     **As a result, this field requires PostgreSQL ≥ 9.4 and Psycopg2 ≥ 2.5.4**.
 
 Querying JSONField
-^^^^^^^^^^^^^^^^^^
+------------------
 
 We will use the following example model::
 
@@ -575,7 +576,7 @@ containment and keys with :class:`~django.contrib.postgres.fields.HStoreField`.
 .. _range-fields:
 
 Range Fields
-------------
+============
 
 There are five range field types, corresponding to the built-in range types in
 PostgreSQL. These fields are used to store a range of values; for example the
@@ -588,7 +589,7 @@ information is necessary. The default is lower bound included, upper bound
 excluded.
 
 IntegerRangeField
-^^^^^^^^^^^^^^^^^
+-----------------
 
 .. class:: IntegerRangeField(**options)
 
@@ -598,7 +599,7 @@ IntegerRangeField
     Python.
 
 BigIntegerRangeField
-^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 .. class:: BigIntegerRangeField(**options)
 
@@ -608,7 +609,7 @@ BigIntegerRangeField
     Python.
 
 FloatRangeField
-^^^^^^^^^^^^^^^
+---------------
 
 .. class:: FloatRangeField(**options)
 
@@ -617,7 +618,7 @@ FloatRangeField
     database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in Python.
 
 DateTimeRangeField
-^^^^^^^^^^^^^^^^^^
+------------------
 
 .. class:: DateTimeRangeField(**options)
 
@@ -627,7 +628,7 @@ DateTimeRangeField
     Python.
 
 DateRangeField
-^^^^^^^^^^^^^^
+--------------
 
 .. class:: DateRangeField(**options)
 
@@ -636,7 +637,7 @@ DateRangeField
     database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python.
 
 Querying Range Fields
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
 
 There are a number of custom lookups and transforms for range fields. They are
 available on all the above fields, but we will use the following example
@@ -675,7 +676,7 @@ operators ``@>``, ``<@``, and ``&&`` respectively.
 .. fieldlookup:: rangefield.contains
 
 contains
-''''''''
+^^^^^^^^
 
     >>> Event.objects.filter(ages__contains=NumericRange(4, 5))
     <QuerySet [<Event: Soft play>]>
@@ -683,7 +684,7 @@ contains
 .. fieldlookup:: rangefield.contained_by
 
 contained_by
-''''''''''''
+^^^^^^^^^^^^
 
     >>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
     <QuerySet [<Event: Soft play>]>
@@ -707,7 +708,7 @@ contained_by
 .. fieldlookup:: rangefield.overlap
 
 overlap
-'''''''
+^^^^^^^
 
     >>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
     <QuerySet [<Event: Soft play>]>
@@ -724,7 +725,7 @@ the specific range comparison operators.
 .. fieldlookup:: rangefield.fully_lt
 
 fully_lt
-''''''''
+^^^^^^^^
 
 The returned ranges are strictly less than the passed range. In other words,
 all the points in the returned range are less than all those in the passed
@@ -736,7 +737,7 @@ range.
 .. fieldlookup:: rangefield.fully_gt
 
 fully_gt
-''''''''
+^^^^^^^^
 
 The returned ranges are strictly greater than the passed range. In other words,
 the all the points in the returned range are greater than all those in the
@@ -748,7 +749,7 @@ passed range.
 .. fieldlookup:: rangefield.not_lt
 
 not_lt
-''''''
+^^^^^^
 
 The returned ranges do not contain any points less than the passed range, that
 is the lower bound of the returned range is at least the lower bound of the
@@ -760,7 +761,7 @@ passed range.
 .. fieldlookup:: rangefield.not_gt
 
 not_gt
-''''''
+^^^^^^
 
 The returned ranges do not contain any points greater than the passed range, that
 is the upper bound of the returned range is at most the upper bound of the
@@ -772,7 +773,7 @@ passed range.
 .. fieldlookup:: rangefield.adjacent_to
 
 adjacent_to
-'''''''''''
+^^^^^^^^^^^
 
 The returned ranges share a bound with the passed range.
 
@@ -788,7 +789,7 @@ lower or upper bound, or query based on emptiness.
 .. fieldlookup:: rangefield.startswith
 
 startswith
-''''''''''
+^^^^^^^^^^
 
 Returned objects have the given lower bound. Can be chained to valid lookups
 for the base field.
@@ -799,7 +800,7 @@ for the base field.
 .. fieldlookup:: rangefield.endswith
 
 endswith
-''''''''
+^^^^^^^^
 
 Returned objects have the given upper bound. Can be chained to valid lookups
 for the base field.
@@ -810,7 +811,7 @@ for the base field.
 .. fieldlookup:: rangefield.isempty
 
 isempty
-'''''''
+^^^^^^^
 
 Returned objects are empty ranges. Can be chained to valid lookups for a
 :class:`~django.db.models.BooleanField`.

docs/ref/contrib/postgres/forms.txt

@@ -1,3 +1,4 @@
+===========================================
 PostgreSQL specific form fields and widgets
 ===========================================
 
@@ -6,6 +7,9 @@ All of these fields and widgets are available from the
 
 .. currentmodule:: django.contrib.postgres.forms
 
+Fields
+======
+
 SimpleArrayField
 ----------------
 
@@ -217,10 +221,10 @@ DateRangeField
     :class:`~django.contrib.postgres.fields.DateRangeField`.
 
 Widgets
--------
+=======
 
 RangeWidget
-~~~~~~~~~~~
+-----------
 
 .. class:: RangeWidget(base_widget, attrs=None)
 

docs/ref/contrib/postgres/functions.txt

@@ -1,3 +1,4 @@
+======================================
 PostgreSQL specific database functions
 ======================================
 
@@ -7,7 +8,7 @@ All of these functions are available from the
 .. currentmodule:: django.contrib.postgres.functions
 
 TransactionNow
---------------
+==============
 
 .. class:: TransactionNow()
 

docs/ref/contrib/postgres/index.txt

@@ -1,3 +1,4 @@
+===========================
 ``django.contrib.postgres``
 ===========================
 

docs/ref/contrib/postgres/operations.txt

@@ -1,3 +1,4 @@
+=============================
 Database migration operations
 =============================
 
@@ -7,7 +8,7 @@ the ``django.contrib.postgres.operations`` module.
 .. currentmodule:: django.contrib.postgres.operations
 
 CreateExtension
----------------
+===============
 
 .. class:: CreateExtension(name)
 
@@ -18,7 +19,7 @@ CreateExtension
         This is a required argument. The name of the extension to be installed.
 
 HStoreExtension
----------------
+===============
 
 .. class:: HStoreExtension()
 
@@ -27,7 +28,7 @@ HStoreExtension
     connection to interpret hstore data.
 
 UnaccentExtension
------------------
+=================
 
 .. class:: UnaccentExtension()
 

docs/ref/contrib/postgres/validators.txt

@@ -5,7 +5,7 @@ Validators
 .. module:: django.contrib.postgres.validators
 
 ``KeysValidator``
------------------
+=================
 
 .. class:: KeysValidator(keys, strict=False, messages=None)
 
@@ -20,7 +20,7 @@ Validators
         the value of a key is non-empty.
 
 Range validators
-----------------
+================
 
 .. class:: RangeMaxValueValidator(limit_value, message=None)
 

docs/ref/files/file.txt

@@ -1,3 +1,4 @@
+===================
 The ``File`` object
 ===================
 
@@ -7,7 +8,7 @@ for basic file handling in Django.
 .. currentmodule:: django.core.files
 
 The ``File`` Class
-------------------
+==================
 
 .. class:: File(file_object)
 
@@ -90,7 +91,7 @@ The ``File`` Class
 .. currentmodule:: django.core.files.base
 
 The ``ContentFile`` Class
--------------------------
+=========================
 
 .. class:: ContentFile(File)
 
@@ -107,7 +108,7 @@ The ``ContentFile`` Class
 .. currentmodule:: django.core.files.images
 
 The ``ImageFile`` Class
------------------------
+=======================
 
 .. class:: ImageFile(file_object)
 
@@ -127,7 +128,7 @@ The ``ImageFile`` Class
 .. currentmodule:: django.core.files
 
 Additional methods on files attached to objects
------------------------------------------------
+===============================================
 
 Any :class:`File` that is associated with an object (as with ``Car.photo``,
 below) will also have a couple of extra methods:

docs/ref/files/storage.txt

@@ -1,10 +1,11 @@
+================
 File storage API
 ================
 
 .. module:: django.core.files.storage
 
 Getting the current storage class
----------------------------------
+=================================
 
 Django provides two convenient ways to access the current storage class:
 
@@ -27,7 +28,7 @@ Django provides two convenient ways to access the current storage class:
     raised if the import is unsuccessful.
 
 The FileSystemStorage Class
----------------------------
+===========================
 
 .. class:: FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)
 
@@ -62,7 +63,7 @@ The FileSystemStorage Class
         an exception if the given file name does not exist.
 
 The Storage Class
------------------
+=================
 
 .. class:: Storage
 

docs/ref/files/uploads.txt

@@ -137,7 +137,7 @@ All file upload handlers should be subclasses of
 handlers wherever you wish.
 
 Required methods
-~~~~~~~~~~~~~~~~
+----------------
 
 Custom file upload handlers **must** define the following methods:
 
@@ -171,7 +171,7 @@ Custom file upload handlers **must** define the following methods:
     the ``UploadedFile`` object should come from subsequent upload handlers.
 
 Optional methods
-~~~~~~~~~~~~~~~~
+----------------
 
 Custom upload handlers may also define any of the following optional methods or
 attributes:

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()
 
@@ -201,7 +201,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::
@@ -213,7 +213,7 @@ what happens with unbound forms::
     {}
 
 Dynamic initial values
-----------------------
+======================
 
 .. attribute:: Form.initial
 
@@ -249,7 +249,7 @@ precedence::
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
 Checking which form data has changed
-------------------------------------
+====================================
 
 .. method:: Form.has_changed()
 
@@ -286,7 +286,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
 
@@ -320,7 +320,7 @@ process::
     '<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>'
 
 Accessing "clean" data
-----------------------
+======================
 
 .. attribute:: Form.cleaned_data
 
@@ -414,7 +414,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::
@@ -476,7 +476,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()
 
@@ -493,7 +493,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()
 
@@ -512,7 +512,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()
 
@@ -532,7 +532,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
@@ -571,7 +571,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
 
@@ -693,7 +693,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
@@ -727,7 +727,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
@@ -761,7 +761,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
@@ -785,7 +785,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.
@@ -824,7 +824,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
 
@@ -922,7 +922,7 @@ Attributes of ``BoundField``
         message
 
 Methods of ``BoundField``
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 .. method:: BoundField.as_hidden(attrs=None, **kwargs)
 
@@ -995,7 +995,7 @@ Methods of ``BoundField``
         hi
 
 Customizing ``BoundField``
---------------------------
+==========================
 
 .. versionadded:: 1.9
 
@@ -1039,7 +1039,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.
@@ -1080,7 +1080,7 @@ form data *and* file data::
     >>> f = ContactFormWithMugshot()
 
 Testing for multipart forms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 .. method:: Form.is_multipart()
 
@@ -1103,7 +1103,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.
@@ -1164,7 +1164,7 @@ by setting the name of the field to ``None`` on the subclass. For example::
 .. _form-prefix:
 
 Prefixes for forms
-------------------
+==================
 
 .. attribute:: Form.prefix
 

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
 
@@ -138,7 +138,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
 
@@ -206,7 +206,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
 
@@ -214,7 +214,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
 
@@ -253,7 +253,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
 
@@ -280,7 +280,7 @@ In the `built-in Field classes`_ section below, each ``Field`` defines the
 error message keys it uses.
 
 ``validators``
-~~~~~~~~~~~~~~
+--------------
 
 .. attribute:: Field.validators
 
@@ -290,18 +290,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
 
@@ -313,10 +313,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()
 
@@ -328,7 +328,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.
@@ -338,7 +338,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)
 
@@ -358,7 +358,7 @@ For each field, we describe the default widget used if you don't specify
         creating the ``BooleanField``.
 
 ``CharField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: CharField(**kwargs)
 
@@ -385,7 +385,7 @@ For each field, we describe the default widget used if you don't specify
        trailing whitespace.
 
 ``ChoiceField``
-~~~~~~~~~~~~~~~
+---------------
 
 .. class:: ChoiceField(**kwargs)
 
@@ -410,7 +410,7 @@ For each field, we describe the default widget used if you don't specify
         callable, it is evaluated each time the field's form is initialized.
 
 ``TypedChoiceField``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. class:: TypedChoiceField(**kwargs)
 
@@ -442,7 +442,7 @@ For each field, we describe the default widget used if you don't specify
         accordingly.
 
 ``DateField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: DateField(**kwargs)
 
@@ -478,10 +478,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)
 
@@ -511,10 +511,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)
 
@@ -552,7 +552,7 @@ For each field, we describe the default widget used if you don't specify
         The maximum number of decimal places permitted.
 
 ``DurationField``
-~~~~~~~~~~~~~~~~~
+-----------------
 
 .. class:: DurationField(**kwargs)
 
@@ -567,7 +567,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)
 
@@ -583,7 +583,7 @@ For each field, we describe the default widget used if you don't specify
     given length.
 
 ``FileField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: FileField(**kwargs)
 
@@ -611,7 +611,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)
 
@@ -654,7 +654,7 @@ For each field, we describe the default widget used if you don't specify
 
 
 ``FloatField``
-~~~~~~~~~~~~~~
+--------------
 
 .. class:: FloatField(**kwargs)
 
@@ -671,7 +671,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)
 
@@ -703,7 +703,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)
 
@@ -727,7 +727,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)
 
@@ -762,7 +762,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)
 
@@ -779,7 +779,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)
 
@@ -801,7 +801,7 @@ For each field, we describe the default widget used if you don't specify
     :class:`TypedChoiceField`.
 
 ``NullBooleanField``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. class:: NullBooleanField(**kwargs)
 
@@ -811,7 +811,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)
 
@@ -840,7 +840,7 @@ For each field, we describe the default widget used if you don't specify
         regex validation.
 
 ``SlugField``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: SlugField(**kwargs)
 
@@ -864,7 +864,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)
 
@@ -888,7 +888,7 @@ For each field, we describe the default widget used if you don't specify
         '%H:%M',        # '14:30'
 
 ``URLField``
-~~~~~~~~~~~~
+------------
 
 .. class:: URLField(**kwargs)
 
@@ -906,7 +906,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``
-~~~~~~~~~~~~~
+-------------
 
 .. class:: UUIDField(**kwargs)
 
@@ -919,10 +919,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)
 
@@ -950,7 +950,7 @@ Slightly complex built-in ``Field`` classes
             ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
 
 ``MultiValueField``
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 .. class:: MultiValueField(fields=(), **kwargs)
 
@@ -1033,7 +1033,7 @@ Slightly complex built-in ``Field`` classes
         This method must be implemented in the subclasses.
 
 ``SplitDateTimeField``
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 .. class:: SplitDateTimeField(**kwargs)
 
@@ -1064,7 +1064,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
@@ -1087,7 +1087,7 @@ method::
             self.fields['foo_select'].queryset = ...
 
 ``ModelChoiceField``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. class:: ModelChoiceField(**kwargs)
 
@@ -1180,7 +1180,7 @@ method::
                 return "My Object #%i" % obj.id
 
 ``ModelMultipleChoiceField``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 .. class:: ModelMultipleChoiceField(**kwargs)
 
@@ -1208,7 +1208,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

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.

docs/ref/forms/models.txt

@@ -61,8 +61,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.
 

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

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
@@ -257,6 +257,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.
@@ -410,7 +413,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,
@@ -421,7 +424,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``.
 
@@ -496,7 +499,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``
 ~~~~~~~~~~~~~~~~~
@@ -513,7 +516,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
@@ -534,7 +537,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`.
 
@@ -548,7 +551,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
 .. _selector-widgets:
 
 Selector and checkbox widgets
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
 ``CheckboxInput``
 ~~~~~~~~~~~~~~~~~
@@ -712,7 +715,7 @@ When looping over the checkboxes, the ``label`` and ``input`` tags include
 .. _file-upload-widgets:
 
 File upload widgets
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 ``FileInput``
 ~~~~~~~~~~~~~
@@ -733,7 +736,7 @@ File upload widgets
 .. _composite-widgets:
 
 Composite widgets
-^^^^^^^^^^^^^^^^^
+-----------------
 
 ``MultipleHiddenInput``
 ~~~~~~~~~~~~~~~~~~~~~~~

docs/ref/models/database-functions.txt

@@ -24,7 +24,7 @@ allows the field to have two "empty values", but it's important for the
 ``Coalesce`` example below.
 
 Coalesce
---------
+========
 
 .. class:: Coalesce(*expressions, **extra)
 
@@ -65,7 +65,7 @@ Usage examples::
     >>> Coalesce('updated', now_sql)
 
 Concat
-------
+======
 
 .. class:: Concat(*expressions, **extra)
 
@@ -92,7 +92,7 @@ Usage example::
     Margaret Smith (Maggie)
 
 Greatest
---------
+========
 
 .. class:: Greatest(*expressions, **extra)
 
@@ -136,7 +136,7 @@ and ``comment.modified``.
     a sensible minimum value to provide as a default.
 
 Least
------
+=====
 
 .. class:: Least(*expressions, **extra)
 
@@ -160,7 +160,7 @@ will result in a database error.
     a sensible maximum value to provide as a default.
 
 Length
-------
+======
 
 .. class:: Length(expression, **extra)
 
@@ -191,7 +191,7 @@ It can also be registered as a transform. For example::
     The ability to register the function as a transform was added.
 
 Lower
-------
+=====
 
 .. class:: Lower(expression, **extra)
 
@@ -213,7 +213,7 @@ Usage example::
     The ability to register the function as a transform was added.
 
 Now
----
+===
 
 .. class:: Now()
 
@@ -236,7 +236,7 @@ Usage example::
     timestamp, use :class:`django.contrib.postgres.functions.TransactionNow`.
 
 Substr
-------
+======
 
 .. class:: Substr(expression, pos, length=None, **extra)
 
@@ -255,7 +255,7 @@ Usage example::
     marga
 
 Upper
-------
+=====
 
 .. class:: Upper(expression, **extra)
 

docs/ref/models/lookups.txt

@@ -31,7 +31,7 @@ A lookup expression consists of three parts:
 .. _lookup-registration-api:
 
 Registration API
-~~~~~~~~~~~~~~~~
+================
 
 Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface to
 register lookups on itself. The two prominent examples are
@@ -75,7 +75,7 @@ follow this API.
 .. _query-expression:
 
 The Query Expression API
-~~~~~~~~~~~~~~~~~~~~~~~~
+========================
 
 The query expression API is a common set of methods that classes define to be
 usable in query expressions to translate themselves into SQL expressions. Direct
@@ -118,7 +118,7 @@ following methods:
     be a :class:`~django.db.models.Field` instance.
 
 Transform reference
-~~~~~~~~~~~~~~~~~~~
+===================
 
 .. class:: Transform
 
@@ -163,7 +163,7 @@ Transform reference
         its ``lhs.output_field``.
 
 Lookup reference
-~~~~~~~~~~~~~~~~
+================
 
 .. class:: Lookup
 

docs/ref/models/meta.txt

@@ -24,7 +24,7 @@ Field access API
 ================
 
 Retrieving a single field instance of a model by name
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------
 
 .. method:: Options.get_field(field_name)
 
@@ -62,7 +62,7 @@ Retrieving a single field instance of a model by name
         FieldDoesNotExist: User has no field named 'does_not_exist'
 
 Retrieving all field instances of a model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 .. method:: Options.get_fields(include_parents=True, include_hidden=False)
 

docs/ref/models/relations.txt

@@ -178,7 +178,7 @@ Related objects reference
        related manager's methods are disabled.
 
 Direct Assignment
------------------
+=================
 
 A related object set can be replaced in bulk with one operation by assigning a
 new iterable of objects to it::

docs/ref/templates/builtins.txt

@@ -10,14 +10,14 @@ documentation for any custom tags or filters installed.
 .. _ref-templates-builtins-tags:
 
 Built-in tag reference
-----------------------
+======================
 
 .. highlight:: html+django
 
 .. templatetag:: autoescape
 
 autoescape
-^^^^^^^^^^
+----------
 
 Controls the current auto-escaping behavior. This tag takes either ``on`` or
 ``off`` as an argument and that determines whether auto-escaping is in effect
@@ -41,7 +41,7 @@ Sample usage::
 .. templatetag:: block
 
 block
-^^^^^
+-----
 
 Defines a block that can be overridden by child templates. See
 :ref:`Template inheritance <template-inheritance>` for more information.
@@ -49,7 +49,7 @@ Defines a block that can be overridden by child templates. See
 .. templatetag:: comment
 
 comment
-^^^^^^^
+-------
 
 Ignores everything between ``{% comment %}`` and ``{% endcomment %}``.
 An optional note may be inserted in the first tag. For example, this is
@@ -67,7 +67,7 @@ Sample usage::
 .. templatetag:: csrf_token
 
 csrf_token
-^^^^^^^^^^
+----------
 
 This tag is used for CSRF protection, as described in the documentation for
 :doc:`Cross Site Request Forgeries </ref/csrf>`.
@@ -75,7 +75,7 @@ This tag is used for CSRF protection, as described in the documentation for
 .. templatetag:: cycle
 
 cycle
-^^^^^
+-----
 
 Produces one of its arguments each time this tag is encountered. The first
 argument is produced on the first encounter, the second argument on the second
@@ -188,7 +188,7 @@ call to ``{% cycle %}`` doesn't specify ``silent``::
 .. templatetag:: debug
 
 debug
-^^^^^
+-----
 
 Outputs a whole load of debugging information, including the current context
 and imported modules.
@@ -196,7 +196,7 @@ and imported modules.
 .. templatetag:: extends
 
 extends
-^^^^^^^
+-------
 
 Signals that this template extends a parent template.
 
@@ -215,7 +215,7 @@ See :ref:`template-inheritance` for more information.
 .. templatetag:: filter
 
 filter
-^^^^^^
+------
 
 Filters the contents of the block through one or more filters. Multiple
 filters can be specified with pipes and filters can have arguments, just as
@@ -239,7 +239,7 @@ Sample usage::
 .. templatetag:: firstof
 
 firstof
-^^^^^^^
+-------
 
 Outputs the first argument variable that is not ``False``. Outputs nothing if
 all the passed variables are ``False``.
@@ -283,7 +283,7 @@ output inside a variable.
 .. templatetag:: for
 
 for
-^^^
+---
 
 Loops over each item in an array, making the item available in a context
 variable. For example, to display a list of athletes provided in
@@ -341,7 +341,7 @@ Variable                    Description
 ==========================  ===============================================
 
 for ... empty
-^^^^^^^^^^^^^
+-------------
 
 The ``for`` tag can take an optional ``{% empty %}`` clause whose text is
 displayed if the given array is empty or could not be found::
@@ -370,7 +370,7 @@ than -- the following::
 .. templatetag:: if
 
 if
-^^
+--
 
 The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
 exists, is not empty, and is not a false boolean value) the contents of the
@@ -392,7 +392,7 @@ clauses, as well as an ``{% else %}`` clause that will be displayed if all
 previous conditions fail. These clauses are optional.
 
 Boolean operators
-"""""""""""""""""
+~~~~~~~~~~~~~~~~~
 
 :ttag:`if` tags may use ``and``, ``or`` or ``not`` to test a number of
 variables or to negate a given variable::
@@ -435,7 +435,7 @@ them to indicate precedence, you should use nested :ttag:`if` tags.
 ``<=``, ``>=`` and ``in`` which work as follows:
 
 ``==`` operator
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Equality. Example::
 
@@ -444,7 +444,7 @@ Equality. Example::
     {% endif %}
 
 ``!=`` operator
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Inequality. Example::
 
@@ -454,7 +454,7 @@ Inequality. Example::
     {% endif %}
 
 ``<`` operator
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 Less than. Example::
 
@@ -463,7 +463,7 @@ Less than. Example::
     {% endif %}
 
 ``>`` operator
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 Greater than. Example::
 
@@ -472,7 +472,7 @@ Greater than. Example::
     {% endif %}
 
 ``<=`` operator
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Less than or equal to. Example::
 
@@ -481,7 +481,7 @@ Less than or equal to. Example::
     {% endif %}
 
 ``>=`` operator
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Greater than or equal to. Example::
 
@@ -490,7 +490,7 @@ Greater than or equal to. Example::
     {% endif %}
 
 ``in`` operator
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Contained within. This operator is supported by many Python containers to test
 whether the given value is in the container. The following are some examples
@@ -511,7 +511,7 @@ of how ``x in y`` will be interpreted::
     {% endif %}
 
 ``not in`` operator
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 
 Not contained within. This is the negation of the ``in`` operator.
 
@@ -525,7 +525,7 @@ you should use::
     {% if a > b and b > c %}
 
 Filters
-"""""""
+~~~~~~~
 
 You can also use filters in the :ttag:`if` expression. For example::
 
@@ -534,7 +534,7 @@ You can also use filters in the :ttag:`if` expression. For example::
     {% endif %}
 
 Complex expressions
-"""""""""""""""""""
+~~~~~~~~~~~~~~~~~~~
 
 All of the above can be combined to form complex expressions. For such
 expressions, it can be important to know how the operators are grouped when the
@@ -563,7 +563,7 @@ Sometimes that is better for clarity anyway, for the sake of those who do not
 know the precedence rules.
 
 ``ifequal`` and ``ifnotequal``
-""""""""""""""""""""""""""""""
+------------------------------
 
 ``{% ifequal a b %} ... {% endifequal %}`` is an obsolete way to write
 ``{% if a == b %} ... {% endif %}``. Likewise, ``{% ifnotequal a b %} ...
@@ -573,7 +573,7 @@ The ``ifequal`` and ``ifnotequal`` tags will be deprecated in a future release.
 .. templatetag:: ifchanged
 
 ifchanged
-^^^^^^^^^
+---------
 
 Check if a value has changed from the last iteration of a loop.
 
@@ -618,7 +618,7 @@ will be displayed if the value has not changed::
 .. templatetag:: include
 
 include
-^^^^^^^
+-------
 
 Loads a template and renders it with the current context. This is a way of
 "including" other templates within a template.
@@ -691,7 +691,7 @@ and returns an empty string.
 .. templatetag:: load
 
 load
-^^^^
+----
 
 Loads a custom template tag set.
 
@@ -713,7 +713,7 @@ more information.
 .. templatetag:: lorem
 
 lorem
-^^^^^
+-----
 
 Displays random "lorem ipsum" Latin text. This is useful for providing sample
 data in templates.
@@ -747,7 +747,7 @@ Examples:
 .. templatetag:: now
 
 now
-^^^
+---
 
 Displays the current date and/or time, using a format according to the given
 string. Such string can contain format specifiers characters as described
@@ -772,7 +772,7 @@ This would display as "It is the 4th of September".
     :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`,
     :setting:`SHORT_DATE_FORMAT` or :setting:`SHORT_DATETIME_FORMAT`.
     The predefined formats may vary depending on the current locale and
-    if :ref:`format-localization` is enabled, e.g.::
+    if :doc:`/topics/i18n/formatting` is enabled, e.g.::
 
         It is {% now "SHORT_DATETIME_FORMAT" %}
 
@@ -786,7 +786,7 @@ output (as a string) inside a variable. This is useful if you want to use
 .. templatetag:: regroup
 
 regroup
-^^^^^^^
+-------
 
 Regroups a list of alike objects by a common attribute.
 
@@ -900,7 +900,7 @@ Another solution is to sort the data in the template using the
     {% regroup cities|dictsort:"country" by country as country_list %}
 
 Grouping on other properties
-""""""""""""""""""""""""""""
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Any valid template lookup is a legal grouping attribute for the regroup
 tag, including methods, attributes, dictionary keys and list items. For
@@ -922,7 +922,7 @@ attribute, allowing  you to group on the display string rather than the
 .. templatetag:: spaceless
 
 spaceless
-^^^^^^^^^
+---------
 
 Removes whitespace between HTML tags. This includes tab
 characters and newlines.
@@ -951,7 +951,7 @@ this example, the space around ``Hello`` won't be stripped::
 .. templatetag:: templatetag
 
 templatetag
-^^^^^^^^^^^
+-----------
 
 Outputs one of the syntax characters used to compose template tags.
 
@@ -980,7 +980,7 @@ Sample usage::
 .. templatetag:: url
 
 url
-^^^
+---
 
 Returns an absolute path reference (a URL without the domain name) matching a
 given view and optional parameters. Any special characters in the resulting
@@ -1061,7 +1061,7 @@ by the context as to the current application.
 .. templatetag:: verbatim
 
 verbatim
-^^^^^^^^
+--------
 
 Stops the template engine from rendering the contents of this block tag.
 
@@ -1082,7 +1082,7 @@ You can also designate a specific closing tag, allowing the use of
 .. templatetag:: widthratio
 
 widthratio
-^^^^^^^^^^
+----------
 
 For creating bar charts and such, this tag calculates the ratio of a given
 value to a maximum value, and then applies that ratio to a constant.
@@ -1105,7 +1105,7 @@ variable. It can be useful, for instance, in a :ttag:`blocktrans` like this::
 .. templatetag:: with
 
 with
-^^^^
+----
 
 Caches a complex variable under a simpler name. This is useful when accessing
 an "expensive" method (e.g., one that hits the database) multiple times.
@@ -1131,12 +1131,12 @@ You can assign more than one context variable::
 .. _ref-templates-builtins-filters:
 
 Built-in filter reference
--------------------------
+=========================
 
 .. templatefilter:: add
 
 add
-^^^
+---
 
 Adds the argument to the value.
 
@@ -1166,7 +1166,7 @@ output will be ``[1, 2, 3, 4, 5, 6]``.
 .. templatefilter:: addslashes
 
 addslashes
-^^^^^^^^^^
+----------
 
 Adds slashes before quotes. Useful for escaping strings in CSV, for example.
 
@@ -1180,7 +1180,7 @@ If ``value`` is ``"I'm using Django"``, the output will be
 .. templatefilter:: capfirst
 
 capfirst
-^^^^^^^^
+--------
 
 Capitalizes the first character of the value. If the first character is not
 a letter, this filter has no effect.
@@ -1194,7 +1194,7 @@ If ``value`` is ``"django"``, the output will be ``"Django"``.
 .. templatefilter:: center
 
 center
-^^^^^^
+------
 
 Centers the value in a field of a given width.
 
@@ -1207,7 +1207,7 @@ If ``value`` is ``"Django"``, the output will be ``"     Django    "``.
 .. templatefilter:: cut
 
 cut
-^^^
+---
 
 Removes all values of arg from the given string.
 
@@ -1221,7 +1221,7 @@ If ``value`` is ``"String with spaces"``, the output will be
 .. templatefilter:: date
 
 date
-^^^^
+----
 
 Formats a date according to the given format.
 
@@ -1350,7 +1350,7 @@ representation of a ``datetime`` value. E.g.::
 .. templatefilter:: default
 
 default
-^^^^^^^
+-------
 
 If value evaluates to ``False``, uses the given default. Otherwise, uses the
 value.
@@ -1364,7 +1364,7 @@ If ``value`` is ``""`` (the empty string), the output will be ``nothing``.
 .. templatefilter:: default_if_none
 
 default_if_none
-^^^^^^^^^^^^^^^
+---------------
 
 If (and only if) value is ``None``, uses the given default. Otherwise, uses the
 value.
@@ -1381,7 +1381,7 @@ If ``value`` is ``None``, the output will be the string ``"nothing"``.
 .. templatefilter:: dictsort
 
 dictsort
-^^^^^^^^
+--------
 
 Takes a list of dictionaries and returns that list sorted by the key given in
 the argument.
@@ -1435,7 +1435,7 @@ then the output would be::
 .. templatefilter:: dictsortreversed
 
 dictsortreversed
-^^^^^^^^^^^^^^^^
+----------------
 
 Takes a list of dictionaries and returns that list sorted in reverse order by
 the key given in the argument. This works exactly the same as the above filter,
@@ -1444,7 +1444,7 @@ but the returned value will be in reverse order.
 .. templatefilter:: divisibleby
 
 divisibleby
-^^^^^^^^^^^
+-----------
 
 Returns ``True`` if the value is divisible by the argument.
 
@@ -1457,7 +1457,7 @@ If ``value`` is ``21``, the output would be ``True``.
 .. templatefilter:: escape
 
 escape
-^^^^^^
+------
 
 Escapes a string's HTML. Specifically, it makes these replacements:
 
@@ -1486,7 +1486,7 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off::
 .. templatefilter:: escapejs
 
 escapejs
-^^^^^^^^
+--------
 
 Escapes characters for use in JavaScript strings. This does *not* make the
 string safe for use in HTML, but does protect you from syntax errors when using
@@ -1502,7 +1502,7 @@ the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u00
 .. templatefilter:: filesizeformat
 
 filesizeformat
-^^^^^^^^^^^^^^
+--------------
 
 Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``,
 ``'4.1 MB'``, ``'102 bytes'``, etc.).
@@ -1524,7 +1524,7 @@ If ``value`` is 123456789, the output would be ``117.7 MB``.
 .. templatefilter:: first
 
 first
-^^^^^
+-----
 
 Returns the first item in a list.
 
@@ -1537,7 +1537,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``.
 .. templatefilter:: floatformat
 
 floatformat
-^^^^^^^^^^^
+-----------
 
 When used without an argument, rounds a floating-point number to one decimal
 place -- but only if there's a decimal part to be displayed. For example:
@@ -1590,7 +1590,7 @@ with an argument of ``-1``.
 .. templatefilter:: force_escape
 
 force_escape
-^^^^^^^^^^^^
+------------
 
 Applies HTML escaping to a string (see the :tfilter:`escape` filter for
 details). This filter is applied *immediately* and returns a new, escaped
@@ -1608,7 +1608,7 @@ the :tfilter:`linebreaks` filter::
 .. templatefilter:: get_digit
 
 get_digit
-^^^^^^^^^
+---------
 
 Given a whole number, returns the requested digit, where 1 is the right-most
 digit, 2 is the second-right-most digit, etc. Returns the original value for
@@ -1624,7 +1624,7 @@ If ``value`` is ``123456789``, the output will be ``8``.
 .. templatefilter:: iriencode
 
 iriencode
-^^^^^^^^^
+---------
 
 Converts an IRI (Internationalized Resource Identifier) to a string that is
 suitable for including in a URL. This is necessary if you're trying to use
@@ -1642,7 +1642,7 @@ If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&amp;me=2"``.
 .. templatefilter:: join
 
 join
-^^^^
+----
 
 Joins a list with a string, like Python's ``str.join(list)``
 
@@ -1656,7 +1656,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string
 .. templatefilter:: last
 
 last
-^^^^
+----
 
 Returns the last item in a list.
 
@@ -1670,7 +1670,7 @@ string ``"d"``.
 .. templatefilter:: length
 
 length
-^^^^^^
+------
 
 Returns the length of the value. This works for both strings and lists.
 
@@ -1686,7 +1686,7 @@ The filter returns ``0`` for an undefined variable.
 .. templatefilter:: length_is
 
 length_is
-^^^^^^^^^
+---------
 
 Returns ``True`` if the value's length is the argument, or ``False`` otherwise.
 
@@ -1700,7 +1700,7 @@ If ``value`` is ``['a', 'b', 'c', 'd']`` or ``"abcd"``, the output will be
 .. templatefilter:: linebreaks
 
 linebreaks
-^^^^^^^^^^
+----------
 
 Replaces line breaks in plain text with appropriate HTML; a single
 newline becomes an HTML line break (``<br />``) and a new line
@@ -1716,7 +1716,7 @@ slug</p>``.
 .. templatefilter:: linebreaksbr
 
 linebreaksbr
-^^^^^^^^^^^^
+------------
 
 Converts all newlines in a piece of plain text to HTML line breaks
 (``<br />``).
@@ -1731,7 +1731,7 @@ slug``.
 .. templatefilter:: linenumbers
 
 linenumbers
-^^^^^^^^^^^
+-----------
 
 Displays text with line numbers.
 
@@ -1754,7 +1754,7 @@ the output will be::
 .. templatefilter:: ljust
 
 ljust
-^^^^^
+-----
 
 Left-aligns the value in a field of a given width.
 
@@ -1769,7 +1769,7 @@ If ``value`` is ``Django``, the output will be ``"Django    "``.
 .. templatefilter:: lower
 
 lower
-^^^^^
+-----
 
 Converts a string into all lowercase.
 
@@ -1783,7 +1783,7 @@ If ``value`` is ``Totally LOVING this Album!``, the output will be
 .. templatefilter:: make_list
 
 make_list
-^^^^^^^^^
+---------
 
 Returns the value turned into a list. For a string, it's a list of characters.
 For an integer, the argument is cast into an unicode string before creating a
@@ -1800,7 +1800,7 @@ list ``['1', '2', '3']``.
 .. templatefilter:: phone2numeric
 
 phone2numeric
-^^^^^^^^^^^^^
+-------------
 
 Converts a phone number (possibly containing letters) to its numerical
 equivalent.
@@ -1817,7 +1817,7 @@ If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``.
 .. templatefilter:: pluralize
 
 pluralize
-^^^^^^^^^
+---------
 
 Returns a plural suffix if the value is not 1. By default, this suffix is
 ``'s'``.
@@ -1848,14 +1848,14 @@ Example::
 .. templatefilter:: pprint
 
 pprint
-^^^^^^
+------
 
 A wrapper around :func:`pprint.pprint` -- for debugging, really.
 
 .. templatefilter:: random
 
 random
-^^^^^^
+------
 
 Returns a random item from the given list.
 
@@ -1868,7 +1868,7 @@ If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``.
 .. templatefilter:: rjust
 
 rjust
-^^^^^
+-----
 
 Right-aligns the value in a field of a given width.
 
@@ -1883,7 +1883,7 @@ If ``value`` is ``Django``, the output will be ``"    Django"``.
 .. templatefilter:: safe
 
 safe
-^^^^
+----
 
 Marks a string as not requiring further HTML escaping prior to output. When
 autoescaping is off, this filter has no effect.
@@ -1899,7 +1899,7 @@ autoescaping is off, this filter has no effect.
 .. templatefilter:: safeseq
 
 safeseq
-^^^^^^^
+-------
 
 Applies the :tfilter:`safe` filter to each element of a sequence. Useful in
 conjunction with other filters that operate on sequences, such as
@@ -1914,7 +1914,7 @@ individual elements of the sequence.
 .. templatefilter:: slice
 
 slice
-^^^^^
+-----
 
 Returns a slice of the list.
 
@@ -1931,7 +1931,7 @@ If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``.
 .. templatefilter:: slugify
 
 slugify
-^^^^^^^
+-------
 
 Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't
 alphanumerics, underscores, or hyphens. Converts to lowercase. Also strips
@@ -1946,7 +1946,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
 .. templatefilter:: stringformat
 
 stringformat
-^^^^^^^^^^^^
+------------
 
 Formats the variable according to the argument, a string formatting specifier.
 This specifier uses Python string formatting syntax, with the exception that
@@ -1964,7 +1964,7 @@ If ``value`` is ``10``, the output will be ``1.000000E+01``.
 .. templatefilter:: striptags
 
 striptags
-^^^^^^^^^
+---------
 
 Makes all possible efforts to strip all [X]HTML tags.
 
@@ -1988,7 +1988,7 @@ output will be ``"Joel is a slug"``.
 .. templatefilter:: time
 
 time
-^^^^
+----
 
 Formats a time according to the given format.
 
@@ -2034,7 +2034,7 @@ used, without applying any localization.
 .. templatefilter:: timesince
 
 timesince
-^^^^^^^^^
+---------
 
 Formats a date as the time since that date (e.g., "4 days, 6 hours").
 
@@ -2054,7 +2054,7 @@ date that is in the future relative to the comparison point.
 .. templatefilter:: timeuntil
 
 timeuntil
-^^^^^^^^^
+---------
 
 Similar to ``timesince``, except that it measures the time from now until the
 given date or datetime. For example, if today is 1 June 2006 and
@@ -2075,7 +2075,7 @@ date that is in the past relative to the comparison point.
 .. templatefilter:: title
 
 title
-^^^^^
+-----
 
 Converts a string into titlecase by making words start with an uppercase
 character and the remaining characters lowercase. This tag makes no effort to
@@ -2090,7 +2090,7 @@ If ``value`` is ``"my FIRST post"``, the output will be ``"My First Post"``.
 .. templatefilter:: truncatechars
 
 truncatechars
-^^^^^^^^^^^^^
+-------------
 
 Truncates a string if it is longer than the specified number of characters.
 Truncated strings will end with a translatable ellipsis sequence ("...").
@@ -2106,7 +2106,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel i..."``.
 .. templatefilter:: truncatechars_html
 
 truncatechars_html
-^^^^^^^^^^^^^^^^^^
+------------------
 
 Similar to :tfilter:`truncatechars`, except that it is aware of HTML tags. Any
 tags that are opened in the string and not closed before the truncation point
@@ -2124,7 +2124,7 @@ Newlines in the HTML content will be preserved.
 .. templatefilter:: truncatewords
 
 truncatewords
-^^^^^^^^^^^^^
+-------------
 
 Truncates a string after a certain number of words.
 
@@ -2141,7 +2141,7 @@ Newlines within the string will be removed.
 .. templatefilter:: truncatewords_html
 
 truncatewords_html
-^^^^^^^^^^^^^^^^^^
+------------------
 
 Similar to :tfilter:`truncatewords`, except that it is aware of HTML tags. Any
 tags that are opened in the string and not closed before the truncation point,
@@ -2162,7 +2162,7 @@ Newlines in the HTML content will be preserved.
 .. templatefilter:: unordered_list
 
 unordered_list
-^^^^^^^^^^^^^^
+--------------
 
 Recursively takes a self-nested list and returns an HTML unordered list --
 WITHOUT opening and closing <ul> tags.
@@ -2186,7 +2186,7 @@ contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
 .. templatefilter:: upper
 
 upper
-^^^^^
+-----
 
 Converts a string into all uppercase.
 
@@ -2199,7 +2199,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``.
 .. templatefilter:: urlencode
 
 urlencode
-^^^^^^^^^
+---------
 
 Escapes a value for use in a URL.
 
@@ -2224,7 +2224,7 @@ If ``value`` is ``"https://www.example.org/"``, the output will be
 .. templatefilter:: urlize
 
 urlize
-^^^^^^
+------
 
 Converts URLs and email addresses in text into clickable links.
 
@@ -2268,7 +2268,7 @@ Django's built-in :tfilter:`escape` filter. The default value for
 .. templatefilter:: urlizetrunc
 
 urlizetrunc
-^^^^^^^^^^^
+-----------
 
 Converts URLs and email addresses into clickable links just like urlize_, but
 truncates URLs longer than the given character limit.
@@ -2289,7 +2289,7 @@ As with urlize_, this filter should only be applied to plain text.
 .. templatefilter:: wordcount
 
 wordcount
-^^^^^^^^^
+---------
 
 Returns the number of words.
 
@@ -2302,7 +2302,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``4``.
 .. templatefilter:: wordwrap
 
 wordwrap
-^^^^^^^^
+--------
 
 Wraps words at specified line length.
 
@@ -2321,7 +2321,7 @@ If ``value`` is ``Joel is a slug``, the output would be::
 .. templatefilter:: yesno
 
 yesno
-^^^^^
+-----
 
 Maps values for ``True``, ``False``, and (optionally) ``None``, to the strings
 "yes", "no", "maybe", or a custom mapping passed as a comma-separated list, and
@@ -2343,14 +2343,14 @@ Value       Argument                Outputs
 ==========  ======================  ===========================================
 
 Internationalization tags and filters
--------------------------------------
+=====================================
 
 Django provides template tags and filters to control each aspect of
 :doc:`internationalization </topics/i18n/index>` in templates. They allow for
 granular control of translations, formatting, and time zone conversions.
 
 i18n
-^^^^
+----
 
 This library allows specifying translatable text in templates.
 To enable it, set :setting:`USE_I18N` to ``True``, then load it with
@@ -2359,7 +2359,7 @@ To enable it, set :setting:`USE_I18N` to ``True``, then load it with
 See :ref:`specifying-translation-strings-in-template-code`.
 
 l10n
-^^^^
+----
 
 This library provides control over the localization of values in templates.
 You only need to load the library using ``{% load l10n %}``, but you'll often
@@ -2368,7 +2368,7 @@ set :setting:`USE_L10N` to ``True`` so that localization is active by default.
 See :ref:`topic-l10n-templates`.
 
 tz
-^^
+--
 
 This library provides control over time zone conversions in templates.
 Like ``l10n``, you only need to load the library using ``{% load tz %}``,
@@ -2378,25 +2378,25 @@ to local time happens by default.
 See :ref:`time-zones-in-templates`.
 
 Other tags and filters libraries
---------------------------------
+================================
 
 Django comes with a couple of other template-tag libraries that you have to
 enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your
 template with the :ttag:`{% load %}<load>` tag.
 
 django.contrib.humanize
-^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
 
 A set of Django template filters useful for adding a "human touch" to data. See
 :doc:`/ref/contrib/humanize`.
 
 static
-^^^^^^
+------
 
 .. templatetag:: static
 
 static
-""""""
+~~~~~~
 
 To link to static files that are saved in :setting:`STATIC_ROOT` Django ships
 with a :ttag:`static` template tag. If the :mod:`django.contrib.staticfiles`
@@ -2433,7 +2433,7 @@ slightly different call::
 .. templatetag:: get_static_prefix
 
 get_static_prefix
-"""""""""""""""""
+~~~~~~~~~~~~~~~~~
 
 You should prefer the :ttag:`static` template tag, but if you need more control
 over exactly where and how :setting:`STATIC_URL` is injected into the template,
@@ -2454,7 +2454,7 @@ the value multiple times::
 .. templatetag:: get_media_prefix
 
 get_media_prefix
-""""""""""""""""
+~~~~~~~~~~~~~~~~
 
 Similar to the :ttag:`get_static_prefix`, ``get_media_prefix`` populates a
 template variable with the media prefix :setting:`MEDIA_URL`, e.g.::

docs/ref/urlresolvers.txt

@@ -11,7 +11,7 @@
     to work until Django 2.0.
 
 reverse()
----------
+=========
 
 If you need to use something similar to the :ttag:`url` template tag in
 your code, Django provides the following function:
@@ -81,7 +81,7 @@ use for reversing. By default, the root URLconf for the current thread is used.
     results.
 
 reverse_lazy()
---------------
+==============
 
 A lazily evaluated version of `reverse()`_.
 
@@ -101,7 +101,7 @@ URLConf is loaded. Some common cases where this function is necessary are:
   signature.
 
 resolve()
----------
+=========
 
 The ``resolve()`` function can be used for resolving URL paths to the
 corresponding view functions. It has the following signature:
@@ -203,7 +203,7 @@ view would raise a ``Http404`` error before redirecting to it::
         return response
 
 get_script_prefix()
--------------------
+===================
 
 .. function:: get_script_prefix()
 

docs/ref/urls.txt

@@ -5,7 +5,7 @@
 .. module:: django.conf.urls
 
 static()
---------
+========
 
 .. function:: static.static(prefix, view=django.views.static.serve, **kwargs)
 
@@ -19,7 +19,7 @@ Helper function to return a URL pattern for serving files in debug mode::
     ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
 
 url()
------
+=====
 
 .. function:: url(regex, view, kwargs=None, name=None)
 
@@ -37,7 +37,7 @@ See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name``
 parameter is useful.
 
 include()
----------
+=========
 
 .. function:: include(module, namespace=None, app_name=None)
               include(pattern_list)
@@ -86,7 +86,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
     application namespace or remove the instance namespace.
 
 handler400
-----------
+==========
 
 .. data:: handler400
 
@@ -102,7 +102,7 @@ See the documentation about :ref:`the 400 (bad request) view
 <http_bad_request_view>` for more information.
 
 handler403
-----------
+==========
 
 .. data:: handler403
 
@@ -118,7 +118,7 @@ See the documentation about :ref:`the 403 (HTTP Forbidden) view
 <http_forbidden_view>` for more information.
 
 handler404
-----------
+==========
 
 .. data:: handler404
 
@@ -133,7 +133,7 @@ See the documentation about :ref:`the 404 (HTTP Not Found) view
 <http_not_found_view>` for more information.
 
 handler500
-----------
+==========
 
 .. data:: handler500
 

docs/releases/1.1.3.txt

@@ -19,7 +19,7 @@ Backwards incompatible changes
 ==============================
 
 Restricted filters in admin interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The Django administrative interface, django.contrib.admin, supports
 filtering of displayed lists of objects by fields on the corresponding

docs/releases/1.1.4.txt

@@ -19,7 +19,7 @@ Backwards incompatible changes
 ==============================
 
 CSRF exception for AJAX requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 Django includes a CSRF-protection mechanism, which makes use of a
 token inserted into outgoing forms. Middleware then checks for the

docs/releases/1.10.txt

@@ -27,10 +27,10 @@ What's new in Django 1.10
 ...
 
 Minor features
-~~~~~~~~~~~~~~
+--------------
 
 :mod:`django.contrib.admin`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * For sites running on a subpath, the default :attr:`URL for the "View site"
   link <django.contrib.admin.AdminSite.site_url>` at the top of each admin page
@@ -57,12 +57,12 @@ Minor features
   method is now the preferred way of retrieving the change message.
 
 :mod:`django.contrib.admindocs`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 :mod:`django.contrib.auth`
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * The default iteration count for the PBKDF2 password hasher has been increased
   by 25%. This backwards compatible change will not affect users who have
@@ -77,12 +77,12 @@ Minor features
   to allow using it without credentials.
 
 :mod:`django.contrib.contenttypes`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 :mod:`django.contrib.gis`
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * :ref:`Distance lookups <distance-lookups>` now accept expressions as the
   distance value parameter.
@@ -122,39 +122,39 @@ Minor features
   <django.contrib.gis.geos.MultiLineString.closed>` properties.
 
 :mod:`django.contrib.messages`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 :mod:`django.contrib.postgres`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 :mod:`django.contrib.redirects`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 :mod:`django.contrib.sessions`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * The :djadmin:`clearsessions` management command now removes file-based
   sessions.
 
 :mod:`django.contrib.sitemaps`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 :mod:`django.contrib.sites`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * The :class:`~django.contrib.sites.models.Site` model now supports
   :ref:`natural keys <topics-serialization-natural-keys>`.
 
 :mod:`django.contrib.staticfiles`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * The :ttag:`static` template tag now uses ``django.contrib.staticfiles``
   if it's in ``INSTALLED_APPS``. This is especially useful for third-party apps
@@ -163,61 +163,61 @@ Minor features
   not worry about whether or not the ``staticfiles`` app is installed.
 
 :mod:`django.contrib.syndication`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 Cache
-^^^^^
+~~~~~
 
 * The file-based cache backend now uses the highest pickling protocol.
 
 CSRF
-^^^^
+~~~~
 
 * The default :setting:`CSRF_FAILURE_VIEW`, ``views.csrf.csrf_failure()`` now
   accepts an optional ``template_name`` parameter, defaulting to
   ``'403_csrf.html'``, to control the template used to render the page.
 
 Database backends
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 * ...
 
 Email
-^^^^^
+~~~~~
 
 * ...
 
 File Storage
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 * ...
 
 File Uploads
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 * ...
 
 Forms
-^^^^^
+~~~~~
 
 * Form and widget ``Media`` is now served using
   :mod:`django.contrib.staticfiles` if installed.
 
 Generic Views
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
 * The :class:`~django.views.generic.base.View` class can now be imported from
   ``django.views``.
 
 Internationalization
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 * ...
 
 Management Commands
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 * The new :option:`check --fail-level` option allows specifying the message
   level that will cause the command to exit with a non-zero status.
@@ -235,12 +235,12 @@ Management Commands
   exit, instead of opening the interactive shell.
 
 Migrations
-^^^^^^^^^^
+~~~~~~~~~~
 
 * Added support for serialization of ``enum.Enum`` objects.
 
 Models
-^^^^^^
+~~~~~~
 
 * Reverse foreign keys from proxy models are now propagated to their
   concrete class. The reverse relation attached by a
@@ -264,7 +264,7 @@ Models
   may be called without any arguments to return all objects in the queryset.
 
 Requests and Responses
-^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~
 
 * Added ``request.user`` to the debug view.
 
@@ -274,30 +274,30 @@ Requests and Responses
   stream-like object and allow wrapping it with :py:class:`io.TextIOWrapper`.
 
 Serialization
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
 * The ``django.core.serializers.json.DjangoJSONEncoder`` now knows how to
   serialize lazy strings, typically used for translatable content.
 
 Signals
-^^^^^^^
+~~~~~~~
 
 * ...
 
 Templates
-^^^^^^^^^
+~~~~~~~~~
 
 * Added the ``autoescape`` option to the
   :class:`~django.template.backends.django.DjangoTemplates` backend and the
   :class:`~django.template.Engine` class.
 
 Tests
-^^^^^
+~~~~~
 
 * ...
 
 URLs
-^^^^
+~~~~
 
 * An addition in :func:`django.setup()` allows URL resolving that happens
   outside of the request/response cycle (e.g. in management commands and
@@ -305,7 +305,7 @@ URLs
   is set.
 
 Validators
-^^^^^^^^^^
+~~~~~~~~~~
 
 * :class:`~django.core.validators.URLValidator` now limits the length of
   domain name labels to 63 characters and the total length of domain
@@ -323,7 +323,7 @@ Backwards incompatible changes in 1.10
     may appear as a backwards incompatible change.
 
 Database backend API
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 * ...
 
@@ -471,7 +471,7 @@ Features deprecated in 1.10
 ===========================
 
 Direct assignment to a reverse foreign key or many-to-many relation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------------------
 
 Instead of assigning related objects using direct assignment::
 
@@ -486,7 +486,7 @@ added in Django 1.9::
 This prevents confusion about an assignment resulting in an implicit save.
 
 :mod:`django.contrib.gis`
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 * The ``get_srid()`` and ``set_srid()`` methods of
   :class:`~django.contrib.gis.geos.GEOSGeometry` are deprecated in favor
@@ -505,7 +505,7 @@ This prevents confusion about an assignment resulting in an implicit save.
   :attr:`~django.contrib.gis.geos.GEOSGeometry.unary_union` property.
 
 Miscellaneous
-~~~~~~~~~~~~~
+-------------
 
 * The ``makemigrations --exit`` option is deprecated in favor of the
   :option:`makemigrations --check` option.

docs/releases/1.2.4.txt

@@ -19,7 +19,7 @@ Backwards incompatible changes
 ==============================
 
 Restricted filters in admin interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The Django administrative interface, django.contrib.admin, supports
 filtering of displayed lists of objects by fields on the corresponding

docs/releases/1.2.5.txt

@@ -19,7 +19,7 @@ Backwards incompatible changes
 ==============================
 
 CSRF exception for AJAX requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 Django includes a CSRF-protection mechanism, which makes use of a
 token inserted into outgoing forms. Middleware then checks for the
@@ -68,7 +68,7 @@ documentation for your version of Django, as the exact code necessary
 is different for some older versions of Django.
 
 FileField no longer deletes files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 In earlier Django versions, when a model instance containing a
 :class:`~django.db.models.FileField` was deleted,
@@ -82,7 +82,7 @@ yourself (for instance, with a custom management command that can be run
 manually or scheduled to run periodically via e.g. cron).
 
 Use of custom SQL to load initial data in tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 Django provides a custom SQL hooks as a way to inject hand-crafted SQL
 into the database synchronization process. One of the possible uses
@@ -112,7 +112,7 @@ should either insert it using :ref:`test fixtures
 test case.
 
 ModelAdmin.lookup_allowed signature changed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 Django 1.2.4 introduced a method ``lookup_allowed`` on ``ModelAdmin``, to cope
 with a security issue (changeset `[15033]

docs/releases/1.2.txt

@@ -309,7 +309,7 @@ Django's :doc:`internationalization framework </topics/i18n/index>` has been exp
 with locale-aware formatting and form processing. That means, if enabled, dates
 and numbers on templates will be displayed using the format specified for the
 current locale. Django will also use localized formats when parsing data in
-forms. See :ref:`Format localization <format-localization>` for more details.
+forms. See :doc:`/topics/i18n/formatting` for more details.
 
 ``readonly_fields`` in ``ModelAdmin``
 -------------------------------------
@@ -1072,10 +1072,10 @@ to provide localizers the possibility to translate date and time formats. They
 were translatable :term:`translation strings <translation string>` that could
 be recognized because they were all upper case (for example
 :setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`).
-They have been deprecated in favor of the new :ref:`Format localization
-<format-localization>` infrastructure that allows localizers to specify that
-information in a ``formats.py`` file in the corresponding
-``django/conf/locale/<locale name>/`` directory.
+They have been deprecated in favor of the new :doc:`/topics/i18n/formatting` 
+infrastructure that allows localizers to specify that information in a 
+``formats.py`` file in the corresponding ``django/conf/locale/<locale name>/`` 
+directory.
 
 GeoDjango
 ---------
@@ -1089,7 +1089,7 @@ following sections provide information on the most-popular APIs that
 were affected by these changes.
 
 ``SpatialBackend``
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 Prior to the creation of the separate spatial backends, the
 ``django.contrib.gis.db.backend.SpatialBackend`` object was
@@ -1117,7 +1117,7 @@ Would need to be changed::
     PostGISAdaptor = connection.ops.Adapter
 
 ``SpatialRefSys`` and ``GeometryColumns`` models
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models`
 had ``SpatialRefSys`` and ``GeometryColumns`` models for querying

docs/releases/1.3.4.txt

@@ -7,7 +7,7 @@ Django 1.3.4 release notes
 This is the fourth release in the Django 1.3 series.
 
 Host header poisoning
----------------------
+=====================
 
 Some parts of Django -- independent of end-user-written applications -- make
 use of full URLs, including domain name, which are generated from the HTTP Host

docs/releases/1.3.5.txt

@@ -14,7 +14,7 @@ the other we've chosen to take further steps to tighten up Django's code in
 response to independent discovery of potential problems from multiple sources.
 
 Host header poisoning
----------------------
+=====================
 
 Several earlier Django security releases focused on the issue of poisoning the
 HTTP Host header, causing Django to generate URLs pointing to arbitrary,
@@ -35,7 +35,7 @@ Any deviation from this will now be rejected, raising the exception
 :exc:`django.core.exceptions.SuspiciousOperation`.
 
 Redirect poisoning
-------------------
+==================
 
 Also following up on a previous issue: in July of this year, we made changes to
 Django's HTTP redirect classes, performing additional validation of the scheme

docs/releases/1.3.6.txt

@@ -11,7 +11,7 @@ This is the sixth bugfix/security release in the Django 1.3 series.
 
 
 Host header poisoning
----------------------
+=====================
 
 Some parts of Django -- independent of end-user-written applications -- make
 use of full URLs, including domain name, which are generated from the HTTP Host
@@ -36,7 +36,7 @@ This host validation is disabled when ``DEBUG`` is ``True`` or when running test
 
 
 XML deserialization
--------------------
+===================
 
 The XML parser in the Python standard library is vulnerable to a number of
 attacks via external entities and entity expansion. Django uses this parser for
@@ -57,7 +57,7 @@ management command, you will need to ensure they do not contain a DTD.
 
 
 Formset memory exhaustion
--------------------------
+=========================
 
 Previous versions of Django did not validate or limit the form-count data
 provided by the client in a formset's management form, making it possible to
@@ -70,7 +70,7 @@ factory argument).
 
 
 Admin history view information leakage
---------------------------------------
+======================================
 
 In previous versions of Django, an admin user without change permission on a
 model could still view the unicode representation of instances via their admin

docs/releases/1.3.txt

@@ -68,7 +68,7 @@ What's new in Django 1.3
 ========================
 
 Class-based views
-~~~~~~~~~~~~~~~~~
+-----------------
 
 Django 1.3 adds a framework that allows you to use a class as a view.
 This means you can compose a view out of a collection of methods that
@@ -86,7 +86,7 @@ your function-based generic views to class-based
 views <https://docs.djangoproject.com/en/1.4/topics/generic-views-migration/>`_.
 
 Logging
-~~~~~~~
+-------
 
 Django 1.3 adds framework-level support for Python's ``logging``
 module.  This means you can now easily configure and control logging
@@ -97,7 +97,7 @@ handled as a logging activity. See :doc:`the documentation on Django's
 logging interface </topics/logging>` for more details.
 
 Extended static files handling
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Django 1.3 ships with a new contrib app --
 ``django.contrib.staticfiles`` -- to help developers handle the static
@@ -118,7 +118,7 @@ for more details or learn how to :doc:`manage static files
 </howto/static-files/index>`.
 
 unittest2 support
-~~~~~~~~~~~~~~~~~
+-----------------
 
 Python 2.7 introduced some major changes to the ``unittest`` library,
 adding some extremely useful features. To ensure that every Django
@@ -146,7 +146,7 @@ you just won't get any of the nice new unittest2 features.
 .. _unittest2: https://pypi.python.org/pypi/unittest2
 
 Transaction context managers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 Users of Python 2.5 and above may now use transaction management functions as
 `context managers`_. For example::
@@ -157,7 +157,7 @@ Users of Python 2.5 and above may now use transaction management functions as
 .. _context managers: https://docs.python.org/glossary.html#term-context-manager
 
 Configurable delete-cascade
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 :class:`~django.db.models.ForeignKey` and
 :class:`~django.db.models.OneToOneField` now accept an
@@ -170,7 +170,7 @@ For more information, see the :attr:`~django.db.models.ForeignKey.on_delete`
 documentation.
 
 Contextual markers and comments for translatable strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------
 
 For translation strings with ambiguous meaning, you can now
 use the ``pgettext`` function to specify the context of the string.
@@ -182,7 +182,7 @@ For more information, see :ref:`contextual-markers` and
 :ref:`translator-comments`.
 
 Improvements to built-in template tags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
 
 A number of improvements have been made to Django's built-in template tags:
 
@@ -199,7 +199,7 @@ A number of improvements have been made to Django's built-in template tags:
   you to load a single tag or filter from a library.
 
 TemplateResponse
-~~~~~~~~~~~~~~~~
+----------------
 
 It can sometimes be beneficial to allow decorators or middleware to
 modify a response *after* it has been constructed by the view. For
@@ -220,7 +220,7 @@ For more details, see the :doc:`documentation </ref/template-response>`
 on the :class:`~django.template.response.TemplateResponse` class.
 
 Caching changes
-~~~~~~~~~~~~~~~
+---------------
 
 Django 1.3 sees the introduction of several improvements to the
 Django's caching infrastructure.
@@ -247,7 +247,7 @@ caching in Django</topics/cache>`.
 .. _pylibmc: http://sendapatch.se/projects/pylibmc/
 
 Permissions for inactive users
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 If you provide a custom auth backend with ``supports_inactive_user``
 set to ``True``, an inactive ``User`` instance will check the backend
@@ -256,14 +256,14 @@ permission handling. See the :doc:`authentication docs </topics/auth/index>`
 for more details.
 
 GeoDjango
-~~~~~~~~~
+---------
 
 The GeoDjango test suite is now included when
 :ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
 when using :ref:`spatial database backends <spatial-backends>`.
 
 :setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------------------------
 
 Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if
 it contained a suffix beyond the domain name.
@@ -279,7 +279,7 @@ In Django 1.4 this same condition will raise ``DeprecationWarning``,
 and in Django 1.5 will raise an ``ImproperlyConfigured`` exception.
 
 Everything else
-~~~~~~~~~~~~~~~
+---------------
 
 Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added
 lots of big ticket items to Django, like multiple-database support,
@@ -335,7 +335,7 @@ Backwards-incompatible changes in 1.3
 =====================================
 
 CSRF validation now applies to AJAX requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------
 
 Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX
 requests from CSRF verification; due to `security issues`_ reported to
@@ -347,7 +347,7 @@ AJAX requests.
 .. _security issues: https://www.djangoproject.com/weblog/2011/feb/08/security/
 
 Restricted filters in admin interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 Prior to Django 1.2.5, the Django administrative interface allowed
 filtering on any model field or relation -- not just those specified
@@ -357,7 +357,7 @@ admin must be for fields or relations specified in ``list_filter`` or
 ``date_hierarchy``.
 
 Deleting a model doesn't delete associated files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------
 
 In earlier Django versions, when a model instance containing a
 :class:`~django.db.models.FileField` was deleted,
@@ -371,7 +371,7 @@ instance, with a custom management command that can be run manually or
 scheduled to run periodically via e.g. cron).
 
 PasswordInput default rendering behavior
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 The :class:`~django.forms.PasswordInput` form widget, intended for use
 with form fields which represent passwords, accepts a boolean keyword
@@ -394,7 +394,7 @@ explicitly indicate this. For example::
         password = forms.CharField(widget=forms.PasswordInput(render_value=True))
 
 Clearable default widget for FileField
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
 
 Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget
 in addition to :class:`~django.forms.FileInput`. ``ClearableFileInput`` renders
@@ -420,7 +420,7 @@ To return to the previous rendering (without the ability to clear the
             widgets = {'document': forms.FileInput}
 
 New index on database session table
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 Prior to Django 1.3, the database table used by the database backend
 for the :doc:`sessions </topics/http/sessions>` app had no index on
@@ -437,7 +437,7 @@ index can be found by running the ``sqlindexes`` admin command::
     python manage.py sqlindexes sessions
 
 No more naughty words
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Django has historically provided (and enforced) a list of profanities.
 The comments app has enforced this list of profanities, preventing people from
@@ -462,7 +462,7 @@ problem.
 .. _commit that implemented this change: https://code.djangoproject.com/changeset/13996
 
 Localflavor changes
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 Django 1.3 introduces the following backwards-incompatible changes to
 local flavors:
@@ -482,7 +482,7 @@ local flavors:
   ``USStateField`` not including them.
 
 FormSet updates
-~~~~~~~~~~~~~~~
+---------------
 
 In Django 1.3 ``FormSet`` creation behavior is modified slightly. Historically
 the class didn't make a distinction between not being passed data and being
@@ -511,7 +511,7 @@ if you need to instantiate an empty ``FormSet``, don't pass in the data or use
     >>> formset = ArticleFormSet(data=None)
 
 Callables in templates
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 Previously, a callable in a template would only be called automatically as part
 of the variable resolution process if it was retrieved via attribute
@@ -529,7 +529,7 @@ designed for web designers, and was never deliberately supported, it is possible
 that some templates may be broken by this change.
 
 Use of custom SQL to load initial data in tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 Django provides a custom SQL hooks as a way to inject hand-crafted SQL
 into the database synchronization process. One of the possible uses
@@ -559,7 +559,7 @@ should either insert it using :ref:`test fixtures
 test case.
 
 Changed priority of translation loading
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
 
 Work has been done to simplify, rationalize and properly document the algorithm
 used by Django at runtime to build translations from the different translations
@@ -605,7 +605,7 @@ domain):
 .. _corresponding deprecated features section: loading_of_project_level_translations_
 
 Transaction management
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 When using managed transactions -- that is, anything but the default
 autocommit mode -- it is important when a transaction is marked as
@@ -639,14 +639,14 @@ the read operation that retrieves the ``MyObject`` instance leaves the
 transaction in a dirty state.
 
 No password reset for inactive users
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 
 Prior to Django 1.3, inactive users were able to request a password reset email
 and reset their password. In Django 1.3 inactive users will receive the same
 message as a nonexistent account.
 
 Password reset view now accepts ``from_email``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 The :func:`django.contrib.auth.views.password_reset` view now accepts a
 ``from_email`` parameter, which is passed to the ``password_reset_form``’s
@@ -679,7 +679,7 @@ be removed entirely.
     </internals/deprecation>`.
 
 ``mod_python`` support
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 The ``mod_python`` library has not had a release since 2007 or a commit since
 2008. The Apache Foundation board voted to remove ``mod_python`` from the set
@@ -694,7 +694,7 @@ recommended by the Django project, but FastCGI is also supported. Support for
 ``mod_python`` deployment will be removed in Django 1.5.
 
 Function-based generic views
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 As a result of the introduction of class-based generic views, the
 function-based generic views provided by Django have been deprecated.
@@ -706,7 +706,7 @@ The following modules and the views they contain have been deprecated:
 * ``django.views.generic.simple``
 
 Test client response ``template`` attribute
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 Django's :ref:`test client <test-client>` returns
 :class:`~django.test.Response` objects annotated with extra testing
@@ -722,7 +722,7 @@ In Django 1.3 the ``template`` attribute is deprecated in favor of a new
 list, even if it has only a single element or no elements.
 
 ``DjangoTestRunner``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 As a result of the introduction of support for unittest2, the features
 of ``django.test.simple.DjangoTestRunner`` (including fail-fast
@@ -731,7 +731,7 @@ redundancy, ``DjangoTestRunner`` has been turned into an empty placeholder
 class, and will be removed entirely in Django 1.5.
 
 Changes to ``url`` and ``ssi``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Most template tags will allow you to pass in either constants or
 variables as arguments -- for example::
@@ -771,7 +771,7 @@ templates should be modified to use the new ``future`` libraries and
 syntax.
 
 Changes to the login methods of the admin
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 In previous version the admin app defined login methods in multiple locations
 and ignored the almost identical implementation in the already used auth app.
@@ -788,7 +788,7 @@ attribute.
 .. _r12634: https://code.djangoproject.com/changeset/12634
 
 ``reset`` and ``sqlreset`` management commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands
 can be used to delete everything. You can also use ALTER TABLE or DROP TABLE
@@ -796,7 +796,7 @@ statements manually.
 
 
 GeoDjango
-~~~~~~~~~
+---------
 
 * The function-based :setting:`TEST_RUNNER` previously used to execute
   the GeoDjango test suite, ``django.contrib.gis.tests.run_gis_tests``, was
@@ -812,7 +812,7 @@ GeoDjango
   called when the SRID of the geometry is less than 0 or ``None``.
 
 ``CZBirthNumberField.clean``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 Previously this field's ``clean()`` method accepted a second, gender, argument
 which allowed stronger validation checks to be made, however since this
@@ -820,7 +820,7 @@ argument could never actually be passed from the Django form machinery it is
 now pending deprecation.
 
 ``CompatCookie``
-~~~~~~~~~~~~~~~~
+----------------
 
 Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class,
 which was a bugfix wrapper around the standard library ``SimpleCookie``. As the
@@ -830,7 +830,7 @@ django.http import SimpleCookie`` instead.
 .. _loading_of_project_level_translations:
 
 Loading of *project-level* translations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
 
 This release of Django starts the deprecation process for inclusion of
 translations located under the so-called *project path* in the translation
@@ -865,7 +865,7 @@ Rationale for this decision:
   inconsistency.
 
 ``PermWrapper`` moved to ``django.contrib.auth.context_processors``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------------------
 
 In Django 1.2, we began the process of changing the location of the
 ``auth`` context processor from ``django.core.context_processors`` to
@@ -877,7 +877,7 @@ moved to ``django.contrib.auth.context_processors``, along with the
 identical to their old versions; only the module location has changed.
 
 Removal of ``XMLField``
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 When Django was first released, Django included an ``XMLField`` that performed
 automatic XML validation for any field input. However, this validation function

docs/releases/1.4.10.txt

@@ -7,7 +7,7 @@ Django 1.4.10 release notes
 Django 1.4.10 fixes a Python-compatibility bug in the 1.4 series.
 
 Python compatibility
---------------------
+====================
 
 Django 1.4.9 inadvertently introduced issues with Python 2.5 compatibility.
 Django 1.4.10 restores Python 2.5 compatibility. This was issue #21362 in

docs/releases/1.4.2.txt

@@ -7,7 +7,7 @@ Django 1.4.2 release notes
 This is the second security release in the Django 1.4 series.
 
 Host header poisoning
----------------------
+=====================
 
 Some parts of Django -- independent of end-user-written applications -- make
 use of full URLs, including domain name, which are generated from the HTTP Host

docs/releases/1.4.3.txt

@@ -14,7 +14,7 @@ the other we've chosen to take further steps to tighten up Django's code in
 response to independent discovery of potential problems from multiple sources.
 
 Host header poisoning
----------------------
+=====================
 
 Several earlier Django security releases focused on the issue of poisoning the
 HTTP Host header, causing Django to generate URLs pointing to arbitrary,
@@ -35,7 +35,7 @@ Any deviation from this will now be rejected, raising the exception
 :exc:`django.core.exceptions.SuspiciousOperation`.
 
 Redirect poisoning
-------------------
+==================
 
 Also following up on a previous issue: in July of this year, we made changes to
 Django's HTTP redirect classes, performing additional validation of the scheme

docs/releases/1.4.4.txt

@@ -12,7 +12,7 @@ This is the fourth bugfix/security release in the Django 1.4 series.
 
 
 Host header poisoning
----------------------
+=====================
 
 Some parts of Django -- independent of end-user-written applications -- make
 use of full URLs, including domain name, which are generated from the HTTP Host
@@ -37,7 +37,7 @@ This host validation is disabled when ``DEBUG`` is ``True`` or when running test
 
 
 XML deserialization
--------------------
+===================
 
 The XML parser in the Python standard library is vulnerable to a number of
 attacks via external entities and entity expansion. Django uses this parser for
@@ -58,7 +58,7 @@ management command, you will need to ensure they do not contain a DTD.
 
 
 Formset memory exhaustion
--------------------------
+=========================
 
 Previous versions of Django did not validate or limit the form-count data
 provided by the client in a formset's management form, making it possible to
@@ -71,7 +71,7 @@ factory argument).
 
 
 Admin history view information leakage
---------------------------------------
+======================================
 
 In previous versions of Django, an admin user without change permission on a
 model could still view the unicode representation of instances via their admin

docs/releases/1.4.6.txt

@@ -10,7 +10,7 @@ the 1.4 series, as well as one other bug.
 This is the sixth bugfix/security release in the Django 1.4 series.
 
 Mitigated possible XSS attack via user-supplied redirect URLs
--------------------------------------------------------------
+=============================================================
 
 Django relies on user input in some cases (e.g.
 :func:`django.contrib.auth.views.login`, ``django.contrib.comments``, and

docs/releases/1.4.7.txt

@@ -8,7 +8,7 @@ Django 1.4.7 fixes one security issue present in previous Django releases in
 the 1.4 series.
 
 Directory traversal vulnerability in ``ssi`` template tag
----------------------------------------------------------
+=========================================================
 
 In previous versions of Django it was possible to bypass the
 ``ALLOWED_INCLUDE_ROOTS`` setting used for security with the ``ssi``

docs/releases/1.4.8.txt

@@ -8,7 +8,7 @@ Django 1.4.8 fixes two security issues present in previous Django releases in
 the 1.4 series.
 
 Denial-of-service via password hashers
---------------------------------------
+======================================
 
 In previous versions of Django, no limit was imposed on the plaintext
 length of a password. This allowed a denial-of-service attack through
@@ -21,7 +21,7 @@ limit on passwords and will fail authentication with any submitted
 password of greater length.
 
 Corrected usage of :func:`~django.views.decorators.debug.sensitive_post_parameters` in :mod:`django.contrib.auth`’s admin
--------------------------------------------------------------------------------------------------------------------------
+=========================================================================================================================
 
 The decoration of the ``add_view`` and ``user_change_password`` user admin
 views with :func:`~django.views.decorators.debug.sensitive_post_parameters`

docs/releases/1.4.9.txt

@@ -8,7 +8,7 @@ Django 1.4.9 fixes a security-related bug in the 1.4 series and one other
 data corruption bug.
 
 Readdressed denial-of-service via password hashers
---------------------------------------------------
+==================================================
 
 Django 1.4.8 imposes a 4096-byte limit on passwords in order to mitigate a
 denial-of-service attack through submission of bogus but extremely large

docs/releases/1.4.txt

@@ -81,7 +81,7 @@ What's new in Django 1.4
 ========================
 
 Support for time zones
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 In previous versions, Django used "naive" date/times (that is, date/times
 without an associated time zone), leaving it up to each developer to interpret
@@ -108,7 +108,7 @@ project, read the :ref:`migration guide <time-zones-migration-guide>`. If you
 encounter problems, there's a helpful :ref:`FAQ <time-zones-faq>`.
 
 Support for in-browser testing frameworks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 Django 1.4 supports integration with in-browser testing frameworks like
 Selenium_. The new :class:`django.test.LiveServerTestCase` base class lets you
@@ -120,7 +120,7 @@ concrete examples.
 .. _Selenium: http://seleniumhq.org/
 
 Updated default project layout and ``manage.py``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------
 
 Django 1.4 ships with an updated default project layout and ``manage.py`` file
 for the :djadmin:`startproject` management command. These fix some issues with
@@ -186,7 +186,7 @@ prefix, some places without it), the imports will need to be cleaned up when
 switching to the new ``manage.py``.
 
 Custom project and app templates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 The :djadmin:`startapp` and :djadmin:`startproject` management commands
 now have a ``--template`` option for specifying a path or URL to a custom app
@@ -207,7 +207,7 @@ For more information, see the :djadmin:`startapp` and :djadmin:`startproject`
 documentation.
 
 Improved WSGI support
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 The :djadmin:`startproject` management command now adds a :file:`wsgi.py`
 module to the initial project layout, containing a simple WSGI application that
@@ -224,7 +224,7 @@ with the same WSGI configuration that is used for deployment. The new
 callable configured via :setting:`WSGI_APPLICATION`.)
 
 ``SELECT FOR UPDATE`` support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 Django 1.4 includes a :meth:`QuerySet.select_for_update()
 <django.db.models.query.QuerySet.select_for_update>` method, which generates a
@@ -236,7 +236,7 @@ For more details, see the documentation for
 :meth:`~django.db.models.query.QuerySet.select_for_update`.
 
 ``Model.objects.bulk_create`` in the ORM
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 This method lets you create multiple objects more efficiently. It can result in
 significant performance increases if you have many objects.
@@ -248,7 +248,7 @@ See the :meth:`~django.db.models.query.QuerySet.bulk_create` docs for more
 information.
 
 ``QuerySet.prefetch_related``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a
 different strategy and broader scope,
@@ -263,7 +263,7 @@ doing O(n) database queries (or worse) if objects on your primary ``QuerySet``
 each have many related objects that you also need to fetch.
 
 Improved password hashing
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 Django's auth system (``django.contrib.auth``) stores passwords using a one-way
 algorithm. Django 1.3 uses the SHA1_ algorithm, but increasing processor speeds
@@ -279,7 +279,7 @@ details, see :ref:`auth_password_storage`.
 .. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt
 
 HTML5 doctype
-~~~~~~~~~~~~~
+-------------
 
 We've switched the admin and other bundled templates to use the HTML5
 doctype. While Django will be careful to maintain compatibility with older
@@ -288,7 +288,7 @@ admin pages without having to lose HTML validity or override the provided
 templates to change the doctype.
 
 List filters in admin interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Prior to Django 1.4, the :mod:`~django.contrib.admin` app let you specify
 change list filters by specifying a field lookup, but it didn't allow you to
@@ -297,7 +297,7 @@ used internally and known as "FilterSpec"). For more details, see the
 documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
 
 Multiple sort in admin interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 The admin change list now supports sorting on multiple columns. It respects all
 elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and
@@ -307,7 +307,7 @@ behavior of desktop GUIs. We also added a
 ordering dynamically (i.e., depending on the request).
 
 New ``ModelAdmin`` methods
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 We added a :meth:`~django.contrib.admin.ModelAdmin.save_related` method to
 :mod:`~django.contrib.admin.ModelAdmin` to ease customization of how
@@ -320,7 +320,7 @@ enable dynamic customization of fields and links displayed on the admin
 change list.
 
 Admin inlines respect user permissions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
 
 Admin inlines now only allow those actions for which the user has
 permission. For ``ManyToMany`` relationships with an auto-created intermediate
@@ -329,7 +329,7 @@ related model determines if the user has the permission to add, change or
 delete relationships.
 
 Tools for cryptographic signing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Django 1.4 adds both a low-level API for signing values and a high-level API
 for setting and reading signed cookies, one of the most common uses of
@@ -339,7 +339,7 @@ See the :doc:`cryptographic signing </topics/signing>` docs for more
 information.
 
 Cookie-based session backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 Django 1.4 introduces a cookie-based session backend that uses the tools for
 :doc:`cryptographic signing </topics/signing>` to store the session data in
@@ -356,7 +356,7 @@ See the :ref:`cookie-based session backend <cookie-session-backend>` docs for
 more information.
 
 New form wizard
-~~~~~~~~~~~~~~~
+---------------
 
 The previous ``FormWizard`` from ``django.contrib.formtools`` has been
 replaced with a new implementation based on the class-based views
@@ -369,13 +369,13 @@ storage backend. The latter uses the tools for
 Django 1.4 to store the wizard's state in the user's cookies.
 
 ``reverse_lazy``
-~~~~~~~~~~~~~~~~
+----------------
 
 A lazily evaluated version of ``reverse()`` was added to allow using URL
 reversals before the project's URLconf gets loaded.
 
 Translating URL patterns
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 Django can now look for a language prefix in the URLpattern when using the new
 :func:`~django.conf.urls.i18n.i18n_patterns` helper function.
@@ -385,7 +385,7 @@ It's also now possible to define translatable URL patterns using
 and how to internationalize URL patterns.
 
 Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------------------------
 
 The :ref:`contextual translation<contextual-markers>` support introduced in
 Django 1.3 via the ``pgettext`` function has been extended to the
@@ -393,7 +393,7 @@ Django 1.3 via the ``pgettext`` function has been extended to the
 keyword.
 
 Customizable ``SingleObjectMixin`` URLConf kwargs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------
 
 Two new attributes,
 :attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>`
@@ -404,14 +404,14 @@ enable the customization of URLconf keyword arguments used for single
 object generic views.
 
 Assignment template tags
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 A new ``assignment_tag`` helper function was added to ``template.Library`` to
 ease the creation of template tags that store data in a specified context
 variable.
 
 ``*args`` and ``**kwargs`` support for template tag helper functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------------------
 
 The :ref:`simple_tag<howto-custom-template-tags-simple-tags>`,
 :ref:`inclusion_tag <howto-custom-template-tags-inclusion-tags>` and newly
@@ -433,7 +433,7 @@ For example:
     {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}
 
 No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
 
 In previous versions of Django, whenever the ``TEMPLATE_DEBUG`` setting
 was ``True``, any exception raised during template rendering (even exceptions
@@ -448,7 +448,7 @@ exceptions from template rendering is now consistent regardless of the value of
 ``TemplateSyntaxError`` in order to catch other errors.
 
 ``truncatechars`` template filter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 This new filter truncates a string to be no longer than the specified
 number of characters. Truncated strings end with a translatable ellipsis
@@ -456,7 +456,7 @@ sequence ("..."). See the documentation for :tfilter:`truncatechars` for
 more details.
 
 ``static`` template tag
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
 ``static`` template tag to refer to files saved with the
@@ -465,7 +465,7 @@ The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
 files from a cloud service<staticfiles-from-cdn>`.
 
 ``CachedStaticFilesStorage`` storage backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------
 
 The :mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a
 :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend
@@ -478,7 +478,7 @@ See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
 docs for more information.
 
 Simple clickjacking protection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 We've added a middleware to provide easy protection against `clickjacking
 <https://en.wikipedia.org/wiki/Clickjacking>`_ using the ``X-Frame-Options``
@@ -487,7 +487,7 @@ you'll almost certainly want to :doc:`enable it </ref/clickjacking/>` to help
 plug that security hole for browsers that support the header.
 
 CSRF improvements
-~~~~~~~~~~~~~~~~~
+-----------------
 
 We've made various improvements to our CSRF features, including the
 :func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator, which can
@@ -497,7 +497,7 @@ improve the security and usefulness of CSRF protection. See the :doc:`CSRF
 docs </ref/csrf>` for more information.
 
 Error report filtering
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 We added two function decorators,
 :func:`~django.views.decorators.debug.sensitive_variables` and
@@ -516,7 +516,7 @@ filter<custom-error-reports>`. For more information see the docs on
 :ref:`Filtering error reports<filtering-error-reports>`.
 
 Extended IPv6 support
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Django 1.4 can now better handle IPv6 addresses with the new
 :class:`~django.db.models.GenericIPAddressField` model field,
@@ -525,7 +525,7 @@ the validators :data:`~django.core.validators.validate_ipv46_address` and
 :data:`~django.core.validators.validate_ipv6_address`.
 
 HTML comparisons in tests
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 The base classes in :mod:`django.test` now have some helpers to
 compare HTML without tripping over irrelevant differences in whitespace,
@@ -540,10 +540,10 @@ client's response contains a given HTML fragment. See the :ref:`assertions
 documentation <assertions>` for more.
 
 Two new date format strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 Two new :tfilter:`date` formats were added for use in template filters,
-template tags and :ref:`format-localization`:
+template tags and :doc:`/topics/i18n/formatting`:
 
 - ``e`` -- the name of the timezone of the given datetime object
 - ``o`` -- the ISO 8601 year number
@@ -562,7 +562,7 @@ But now it needs to also escape ``e`` and ``o``::
 For more information, see the :tfilter:`date` documentation.
 
 Minor features
-~~~~~~~~~~~~~~
+--------------
 
 Django 1.4 also includes several smaller improvements worth noting:
 
@@ -666,7 +666,7 @@ Backwards incompatible changes in 1.4
 =====================================
 
 SECRET_KEY setting is required
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Running Django with an empty or known :setting:`SECRET_KEY` disables many of
 Django's security protections and can lead to remote-code-execution
@@ -680,7 +680,7 @@ due to the severity of the consequences of running Django with no
 :setting:`SECRET_KEY`.
 
 django.contrib.admin
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 The included administration app ``django.contrib.admin`` has for a long time
 shipped with a default set of static files such as JavaScript, images and
@@ -715,7 +715,7 @@ If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
     :file:`django/contrib/admin/static/admin/`.
 
 Supported browsers for the admin
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 Django hasn't had a clear policy on which browsers are supported by the
 admin app. Our new policy formalizes existing practices: `YUI's A-grade`_
@@ -733,7 +733,7 @@ any range of browsers.
 .. _YUI's A-grade: http://yuilibrary.com/yui/docs/tutorials/gbs/
 
 Removed admin icons
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 As part of an effort to improve the performance and usability of the admin's
 change-list sorting interface and :attr:`horizontal
@@ -751,7 +751,7 @@ If you used those icons to customize the admin, then you'll need to replace
 them with your own icons or get the files from a previous release.
 
 CSS class names in admin forms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 To avoid conflicts with other common CSS class names (e.g. "button"), we added
 a prefix ("field-") to all CSS class names automatically generated from the
@@ -761,7 +761,7 @@ style sheets or JavaScript files if you previously used plain field names as
 selectors for custom styles or JavaScript transformations.
 
 Compatibility with old signed data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 Django 1.3 changed the cryptographic signing mechanisms used in a number of
 places in Django. While Django 1.3 kept fallbacks that would accept hashes
@@ -831,7 +831,7 @@ instance:
     password hashes.
 
 django.contrib.flatpages
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 Starting in 1.4, the
 :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only
@@ -845,7 +845,7 @@ Also, redirects returned by flatpages are now permanent (with 301 status code),
 to match the behavior of :class:`~django.middleware.common.CommonMiddleware`.
 
 Serialization of :class:`~datetime.datetime` and :class:`~datetime.time`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------------------------------
 
 As a consequence of time-zone support, and according to the ECMA-262
 specification, we made changes to the JSON serializer:
@@ -865,7 +865,7 @@ Though the serializers now use these new formats when creating fixtures, they
 can still load fixtures that use the old format.
 
 ``supports_timezone`` changed to ``False`` for SQLite
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------
 
 The database feature ``supports_timezone`` used to be ``True`` for SQLite.
 Indeed, if you saved an aware datetime object, SQLite stored a string that
@@ -878,7 +878,7 @@ datetimes are now stored without time-zone information in SQLite. When
 object, Django raises an exception.
 
 ``MySQLdb``-specific exceptions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 The MySQL backend historically has raised ``MySQLdb.OperationalError``
 when a query triggered an exception. We've fixed this bug, and we now raise
@@ -887,7 +887,7 @@ when a query triggered an exception. We've fixed this bug, and we now raise
 clauses.
 
 Database connection's thread-locality
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 ``DatabaseWrapper`` objects (i.e. the connection objects referenced by
 ``django.db.connection`` and ``django.db.connections["some_alias"]``) used to
@@ -913,7 +913,7 @@ Concurrency behavior is defined by the underlying backend implementation.
 Check their documentation for details.
 
 `COMMENTS_BANNED_USERS_GROUP` setting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 Django's comments has historically
 supported excluding the comments of a special user group, but we've never
@@ -950,7 +950,7 @@ Save this model manager in your custom comment app (e.g., in
         objects = BanningCommentManager()
 
 `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------
 
 Until Django 1.3, it was possible to exclude some URLs from Django's
 :doc:`404 error reporting</howto/error-reporting>` by adding prefixes to
@@ -988,7 +988,7 @@ Don't forget to escape characters that have a special meaning in a regular
 expression, such as periods.
 
 CSRF protection extended to PUT and DELETE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 Previously, Django's :doc:`CSRF protection </ref/csrf/>` provided
 protection only against POST requests. Since use of PUT and DELETE methods in
@@ -1000,7 +1000,7 @@ If you're using PUT or DELETE methods in AJAX applications, please see the
 :ref:`instructions about using AJAX and CSRF <csrf-ajax>`.
 
 Password reset view now accepts ``subject_template_name``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------
 
 The ``password_reset`` view in ``django.contrib.auth`` now accepts a
 ``subject_template_name`` parameter, which is passed to the password save form
@@ -1009,21 +1009,21 @@ form, then you will need to ensure your form's ``save()`` method accepts this
 keyword argument.
 
 ``django.core.template_loaders``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 This was an alias to ``django.template.loader`` since 2005, and we've removed it
 without emitting a warning due to the length of the deprecation. If your code
 still referenced this, please use ``django.template.loader`` instead.
 
 ``django.db.models.fields.URLField.verify_exists``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------
 
 This functionality has been removed due to intractable performance and
 security issues. Any existing usage of ``verify_exists`` should be
 removed.
 
 ``django.core.files.storage.Storage.open``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 The ``open`` method of the base Storage class used to take an obscure parameter
 ``mixin`` that allowed you to dynamically change the base classes of the
@@ -1049,7 +1049,7 @@ method, like this::
             return Spam(open(self.path(name), mode))
 
 YAML deserializer now uses ``yaml.safe_load``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------
 
 ``yaml.load`` is able to construct any Python object, which may trigger
 arbitrary code execution if you process a YAML document that comes from an
@@ -1059,7 +1059,7 @@ fixtures are trusted data, the YAML deserializer now uses ``yaml.safe_load``
 for additional security.
 
 Session cookies now have the ``httponly`` flag by default
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------
 
 Session cookies now include the ``httponly`` attribute by default to
 help reduce the impact of potential XSS attacks. As a consequence of
@@ -1069,7 +1069,7 @@ compatibility, use ``SESSION_COOKIE_HTTPONLY = False`` in your
 settings file.
 
 The :tfilter:`urlize` filter no longer escapes every URL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------
 
 When a URL contains a ``%xx`` sequence, where ``xx`` are two hexadecimal
 digits, :tfilter:`urlize` now assumes that the URL is already escaped and
@@ -1078,7 +1078,7 @@ contains a ``%xx`` sequence, but such URLs are very unlikely to happen in the
 wild, because they would confuse browsers too.
 
 ``assertTemplateUsed`` and ``assertTemplateNotUsed`` as context manager
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------------------------
 
 It's now possible to check whether a template was used within a block of
 code with :meth:`~django.test.SimpleTestCase.assertTemplateUsed` and
@@ -1093,7 +1093,7 @@ can be used as a context manager::
 See the :ref:`assertion documentation<assertions>` for more.
 
 Database connections after running the test suite
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------
 
 The default test runner no longer restores the database connections after
 tests' execution. This prevents the production database from being exposed to
@@ -1106,7 +1106,7 @@ subclassing ``DjangoTestRunner`` and overriding its ``teardown_databases()``
 method.
 
 Output of :djadmin:`manage.py help <help>`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 :djadmin:`manage.py help <help>` now groups available commands by application.
 If you depended on the output of this command -- if you parsed it, for example
@@ -1115,7 +1115,7 @@ management commands in a script, use
 :djadmin:`manage.py help --commands <help>` instead.
 
 ``extends`` template tag
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 Previously, the :ttag:`extends` tag used a buggy method of parsing arguments,
 which could lead to it erroneously considering an argument as a string literal
@@ -1126,7 +1126,7 @@ interests of full disclosure, the ``ExtendsNode.__init__`` definition has
 changed, which may break any custom tags that use this class.
 
 Loading some incomplete fixtures no longer works
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------
 
 Prior to 1.4, a default value was inserted for fixture objects that were missing
 a specific date or datetime value when auto_now or auto_now_add was set for the
@@ -1135,7 +1135,7 @@ incomplete fixtures will fail. Because fixtures are a raw import, they should
 explicitly specify all field values, regardless of field options on the model.
 
 Development Server Multithreading
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 The development server is now is multithreaded by default. Use the
 :option:`runserver --nothreading` option to disable the use of threading in the
@@ -1144,7 +1144,7 @@ development server::
     django-admin.py runserver --nothreading
 
 Attributes disabled in markdown when safe mode set
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------
 
 Prior to Django 1.4, attributes were included in any markdown output regardless
 of safe mode setting of the filter. With version > 2.1 of the Python-Markdown
@@ -1155,7 +1155,7 @@ Python-Markdown library less than 2.1, a warning is issued that the output is
 insecure.
 
 FormMixin get_initial returns an instance-specific dictionary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------------
 
 In Django 1.3, the ``get_initial`` method of the
 :class:`django.views.generic.edit.FormMixin` class was returning the
@@ -1169,14 +1169,14 @@ Features deprecated in 1.4
 ==========================
 
 Old styles of calling ``cache_page`` decorator
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 Some legacy ways of calling :func:`~django.views.decorators.cache.cache_page`
 have been deprecated. Please see the documentation for the correct way to use
 this decorator.
 
 Support for PostgreSQL versions older than 8.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 Django 1.3 dropped support for PostgreSQL versions older than 8.0, and we
 suggested using a more recent version because of performance improvements
@@ -1187,7 +1187,7 @@ Django 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL
 version it officially supports.
 
 Request exceptions are now always logged
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 When we added :doc:`logging support </topics/logging/>` in Django in 1.3, the
 admin error email support was moved into the
@@ -1227,7 +1227,7 @@ The existence of any ``'filters'`` key under the ``'mail_admins'`` handler will
 disable this backward-compatibility shim and deprecation warning.
 
 ``django.conf.urls.defaults``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 Until Django 1.3, the functions :func:`~django.conf.urls.include`,
 ``patterns()`` and :func:`~django.conf.urls.url` plus
@@ -1237,7 +1237,7 @@ were located in a ``django.conf.urls.defaults`` module.
 In Django 1.4, they live in :mod:`django.conf.urls`.
 
 ``django.contrib.databrowse``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 Databrowse has not seen active development for some time, and this does not show
 any sign of changing. There had been a suggestion for a `GSOC project`_ to
@@ -1252,7 +1252,7 @@ itself, so it's available to be adopted by an individual or group as
 a third-party project.
 
 ``django.core.management.setup_environ``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 This function temporarily modified ``sys.path`` in order to make the parent
 "project" directory importable under the old flat :djadmin:`startproject`
@@ -1265,7 +1265,7 @@ These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE``
 environment variable or using :func:`django.conf.settings.configure`.
 
 ``django.core.management.execute_manager``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
 
 This function was previously used by ``manage.py`` to execute a management
 command. It is identical to
@@ -1276,7 +1276,7 @@ of these functions is documented as part of the public API, but a deprecation
 path is needed due to use in existing ``manage.py`` files.
 
 ``is_safe`` and ``needs_autoescape`` attributes of template filters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------------------
 
 Two flags, ``is_safe`` and ``needs_autoescape``, define how each template filter
 interacts with Django's auto-escaping behavior. They used to be attributes of
@@ -1299,7 +1299,7 @@ Now, the flags are keyword arguments of :meth:`@register.filter
 See :ref:`filters and auto-escaping <filters-auto-escaping>` for more information.
 
 Wildcard expansion of application names in `INSTALLED_APPS`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------------
 
 Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application
 names, like ``django.contrib.*``. The expansion was performed by a
@@ -1313,14 +1313,14 @@ settings file to list all your applications explicitly.
 .. _this can't be done reliably: https://docs.python.org/tutorial/modules.html#importing-from-a-package
 
 ``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------------
 
 This attribute was confusingly named ``HttpRequest.raw_post_data``, but it
 actually provided the body of the HTTP request. It's been renamed to
 ``HttpRequest.body``, and ``HttpRequest.raw_post_data`` has been deprecated.
 
 ``django.contrib.sitemaps`` bug fix with potential performance implications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------------------------
 
 In previous versions, ``Paginator`` objects used in sitemap classes were
 cached, which could result in stale site maps. We've removed the caching, so
@@ -1332,7 +1332,7 @@ To mitigate the performance impact, consider using the :doc:`caching
 framework </topics/cache>` within your ``Sitemap`` subclass.
 
 Versions of Python-Markdown earlier than 2.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------
 
 Versions of Python-Markdown earlier than 2.1 do not support the option to
 disable attributes. As a security issue, earlier versions of this library will