From bca9faae95db2a92e540fbd08505c134639916fe Mon Sep 17 00:00:00 2001
From: "Elif T. Kus"
Date: Sun, 3 Jan 2016 12:56:22 +0200
Subject: [PATCH] Fixed #26020 -- Normalized header stylings in docs.
---
docs/contents.txt | 4 +-
docs/faq/admin.txt | 21 +-
docs/faq/contributing.txt | 9 +-
docs/faq/general.txt | 27 +--
docs/faq/help.txt | 11 +-
docs/faq/install.txt | 11 +-
docs/faq/models.txt | 13 +-
docs/faq/usage.txt | 11 +-
docs/glossary.txt | 2 -
docs/howto/custom-file-storage.txt | 1 +
docs/howto/custom-lookups.txt | 14 +-
docs/howto/custom-template-tags.txt | 42 ++--
docs/howto/deployment/index.txt | 1 +
docs/howto/deployment/wsgi/index.txt | 6 +-
docs/howto/error-reporting.txt | 13 +-
docs/howto/index.txt | 1 +
docs/howto/outputting-csv.txt | 2 +-
docs/howto/writing-migrations.txt | 6 +-
docs/index.txt | 3 -
.../contributing/bugs-and-features.txt | 8 +-
.../contributing/committing-code.txt | 6 +-
docs/internals/contributing/localizing.txt | 8 +-
.../contributing/new-contributors.txt | 6 +-
.../contributing/triaging-tickets.txt | 44 ++--
.../writing-code/coding-style.txt | 16 +-
.../contributing/writing-code/javascript.txt | 16 +-
.../writing-code/submitting-patches.txt | 30 +--
.../contributing/writing-code/unit-tests.txt | 26 +--
.../writing-code/working-with-git.txt | 19 +-
.../contributing/writing-documentation.txt | 50 ++--
docs/internals/index.txt | 1 +
docs/internals/mailing-lists.txt | 12 +-
docs/internals/security.txt | 2 -
docs/intro/index.txt | 1 +
docs/intro/install.txt | 13 +-
docs/misc/index.txt | 1 +
docs/ref/class-based-views/base.txt | 6 +-
.../ref/class-based-views/flattened-index.txt | 42 ++--
.../class-based-views/generic-date-based.txt | 14 +-
.../ref/class-based-views/generic-display.txt | 4 +-
.../ref/class-based-views/generic-editing.txt | 8 +-
docs/ref/class-based-views/index.txt | 4 +-
.../class-based-views/mixins-date-based.txt | 12 +-
docs/ref/class-based-views/mixins-editing.txt | 8 +-
.../mixins-multiple-object.txt | 4 +-
docs/ref/class-based-views/mixins-simple.txt | 4 +-
.../mixins-single-object.txt | 4 +-
docs/ref/clickjacking.txt | 8 +-
docs/ref/contrib/auth.txt | 1 +
docs/ref/contrib/gis/forms-api.txt | 24 +-
docs/ref/contrib/gis/functions.txt | 52 ++---
docs/ref/contrib/gis/install/geolibs.txt | 12 +-
docs/ref/contrib/gis/install/index.txt | 32 +--
docs/ref/contrib/gis/install/spatialite.txt | 14 +-
docs/ref/contrib/gis/model-api.txt | 4 +-
docs/ref/contrib/gis/testing.txt | 6 +-
docs/ref/contrib/gis/tutorial.txt | 4 +-
docs/ref/contrib/humanize.txt | 16 +-
docs/ref/contrib/postgres/aggregates.txt | 42 ++--
docs/ref/contrib/postgres/fields.txt | 51 ++--
docs/ref/contrib/postgres/forms.txt | 8 +-
docs/ref/contrib/postgres/functions.txt | 3 +-
docs/ref/contrib/postgres/index.txt | 1 +
docs/ref/contrib/postgres/operations.txt | 7 +-
docs/ref/contrib/postgres/validators.txt | 4 +-
docs/ref/files/file.txt | 9 +-
docs/ref/files/storage.txt | 7 +-
docs/ref/files/uploads.txt | 4 +-
docs/ref/forms/api.txt | 48 ++--
docs/ref/forms/fields.txt | 96 ++++----
docs/ref/forms/formsets.txt | 2 +-
docs/ref/forms/models.txt | 4 +-
docs/ref/forms/validation.txt | 21 +-
docs/ref/forms/widgets.txt | 41 ++--
docs/ref/models/database-functions.txt | 18 +-
docs/ref/models/lookups.txt | 8 +-
docs/ref/models/meta.txt | 4 +-
docs/ref/models/relations.txt | 2 +-
docs/ref/templates/builtins.txt | 212 ++++++++---------
docs/ref/urlresolvers.txt | 8 +-
docs/ref/urls.txt | 14 +-
docs/releases/1.1.3.txt | 2 +-
docs/releases/1.1.4.txt | 2 +-
docs/releases/1.10.txt | 74 +++---
docs/releases/1.2.4.txt | 2 +-
docs/releases/1.2.5.txt | 8 +-
docs/releases/1.2.txt | 14 +-
docs/releases/1.3.4.txt | 2 +-
docs/releases/1.3.5.txt | 4 +-
docs/releases/1.3.6.txt | 8 +-
docs/releases/1.3.txt | 84 +++----
docs/releases/1.4.10.txt | 2 +-
docs/releases/1.4.2.txt | 2 +-
docs/releases/1.4.3.txt | 4 +-
docs/releases/1.4.4.txt | 8 +-
docs/releases/1.4.6.txt | 2 +-
docs/releases/1.4.7.txt | 2 +-
docs/releases/1.4.8.txt | 4 +-
docs/releases/1.4.9.txt | 2 +-
docs/releases/1.4.txt | 152 ++++++------
docs/releases/1.5.2.txt | 4 +-
docs/releases/1.5.3.txt | 4 +-
docs/releases/1.5.4.txt | 4 +-
docs/releases/1.5.5.txt | 4 +-
docs/releases/1.5.txt | 88 +++----
docs/releases/1.6.txt | 108 ++++-----
docs/releases/1.7.txt | 198 ++++++++--------
docs/releases/1.8.txt | 204 ++++++++--------
docs/releases/1.9.txt | 124 +++++-----
docs/releases/security.txt | 218 +++++++++---------
.../class-based-views/generic-display.txt | 2 -
.../class-based-views/generic-editing.txt | 9 +-
docs/topics/db/examples/many_to_many.txt | 4 +-
docs/topics/db/examples/many_to_one.txt | 4 +-
docs/topics/db/examples/one_to_one.txt | 4 +-
docs/topics/db/index.txt | 1 +
docs/topics/db/tablespaces.txt | 8 +-
docs/topics/external-packages.txt | 6 +-
docs/topics/forms/formsets.txt | 39 ++--
docs/topics/forms/index.txt | 14 +-
docs/topics/forms/media.txt | 21 +-
docs/topics/forms/modelforms.txt | 8 +-
docs/topics/http/index.txt | 1 +
docs/topics/http/sessions.txt | 4 +-
docs/topics/i18n/formatting.txt | 2 -
docs/topics/i18n/timezones.txt | 2 -
docs/topics/index.txt | 1 +
docs/topics/install.txt | 6 +-
docs/topics/migrations.txt | 46 ++--
docs/topics/performance.txt | 20 +-
docs/topics/serialization.txt | 24 +-
docs/topics/testing/tools.txt | 48 ++--
132 files changed, 1498 insertions(+), 1464 deletions(-)
diff --git a/docs/contents.txt b/docs/contents.txt
index 736e1f62bf6..137b3089218 100644
--- a/docs/contents.txt
+++ b/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`
diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt
index ce89203c760..a1d42099f9b 100644
--- a/docs/faq/admin.txt
+++ b/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 ` 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 `
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.
diff --git a/docs/faq/contributing.txt b/docs/faq/contributing.txt
index cdf2b6c6ca1..079a7891976 100644
--- a/docs/faq/contributing.txt
+++ b/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 `.
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
diff --git a/docs/faq/general.txt b/docs/faq/general.txt
index 4bc8e6dfe36..cb31e8b6abf 100644
--- a/docs/faq/general.txt
+++ b/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 `.
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 `.
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.
does -- 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 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 `.
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
diff --git a/docs/faq/help.txt b/docs/faq/help.txt
index cdc68d40bf6..6cc3ca68c7a 100644
--- a/docs/faq/help.txt
+++ b/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 `.
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,
diff --git a/docs/faq/install.txt b/docs/faq/install.txt
index d4e7f283100..5564955a69e 100644
--- a/docs/faq/install.txt
+++ b/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 `).
@@ -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
diff --git a/docs/faq/models.txt b/docs/faq/models.txt
index 982b806c788..c6a7f28e239 100644
--- a/docs/faq/models.txt
+++ b/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 `.
If I make changes to a model, how do I update the database?
------------------------------------------------------------
+===========================================================
Take a look at Django's support for :mod:`schema 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
diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt
index bd1c250896c..9c659bd711b 100644
--- a/docs/faq/usage.txt
+++ b/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
diff --git a/docs/glossary.txt b/docs/glossary.txt
index c7a16e6b3d6..f24a33e81d5 100644
--- a/docs/glossary.txt
+++ b/docs/glossary.txt
@@ -1,5 +1,3 @@
-.. _glossary:
-
========
Glossary
========
diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt
index 9683dcd20a5..131f5596703 100644
--- a/docs/howto/custom-file-storage.txt
+++ b/docs/howto/custom-file-storage.txt
@@ -1,3 +1,4 @@
+===============================
Writing a custom storage system
===============================
diff --git a/docs/howto/custom-lookups.txt b/docs/howto/custom-lookups.txt
index 488beaf562e..7d7667dc982 100644
--- a/docs/howto/custom-lookups.txt
+++ b/docs/howto/custom-lookups.txt
@@ -10,7 +10,7 @@ explains how to write custom lookups and how to alter the working of existing
lookups. For the API references of lookups, see the :doc:`/ref/models/lookups`.
A simple lookup example
-~~~~~~~~~~~~~~~~~~~~~~~
+=======================
Let's start with a simple custom lookup. We will write a custom lookup ``ne``
which works opposite to ``exact``. ``Author.objects.filter(name__ne='Jack')``
@@ -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
diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index b58d8725bf4..97179de7b0f 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -11,7 +11,7 @@ defining custom tags and filters using Python, and then make them
available to your templates using the :ttag:`{% load %}` 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 ` and
:ref:`filters and time zones ` 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 `.
.. _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:
The time is {{ the_time }}.
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 %}` 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`
@@ -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 %}` 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
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
index 4acde036997..8ffda2cf63b 100644
--- a/docs/howto/deployment/index.txt
+++ b/docs/howto/deployment/index.txt
@@ -1,3 +1,4 @@
+================
Deploying Django
================
diff --git a/docs/howto/deployment/wsgi/index.txt b/docs/howto/deployment/wsgi/index.txt
index 27243e248c3..2579df0c6a4 100644
--- a/docs/howto/deployment/wsgi/index.txt
+++ b/docs/howto/deployment/wsgi/index.txt
@@ -22,7 +22,7 @@ Django includes getting-started documentation for the following WSGI servers:
uwsgi
The ``application`` object
---------------------------
+==========================
The key concept of deploying with WSGI is the ``application`` callable which
the application server uses to communicate with your code. It's commonly
@@ -42,7 +42,7 @@ set to ``.wsgi.application``, which points to the ``application``
callable in :file:`/wsgi.py`.
Configuring the settings module
--------------------------------
+===============================
When the WSGI server loads your application, Django needs to import the
settings module — that's where your entire application is defined.
@@ -68,7 +68,7 @@ If this variable isn't set, the default :file:`wsgi.py` sets it to
Applying WSGI middleware
-------------------------
+========================
To apply `WSGI middleware`_ you can simply wrap the application object. For
instance you could add these lines at the bottom of :file:`wsgi.py`::
diff --git a/docs/howto/error-reporting.txt b/docs/howto/error-reporting.txt
index d27f7343983..fc043375d40 100644
--- a/docs/howto/error-reporting.txt
+++ b/docs/howto/error-reporting.txt
@@ -1,3 +1,4 @@
+===============
Error reporting
===============
@@ -12,10 +13,10 @@ You need to keep track of errors that occur in deployed sites, so Django can be
configured to create reports with details about those errors.
Email reports
--------------
+=============
Server errors
-~~~~~~~~~~~~~
+-------------
When :setting:`DEBUG` is ``False``, Django will email the users listed in the
:setting:`ADMINS` setting whenever your code raises an unhandled exception and
@@ -49,7 +50,7 @@ To activate this behavior, put the email addresses of the recipients in the
`.
404 errors
-~~~~~~~~~~
+----------
Django can also be configured to email errors about broken links (404 "page
not found" errors). Django sends emails about 404 errors when:
@@ -119,7 +120,7 @@ and override its methods.
.. _filtering-error-reports:
Filtering error reports
------------------------
+=======================
.. warning::
@@ -130,7 +131,7 @@ Filtering error reports
through email).
Filtering sensitive information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
.. currentmodule:: django.views.decorators.debug
@@ -231,7 +232,7 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
.. _custom-error-reports:
Custom error reports
-~~~~~~~~~~~~~~~~~~~~
+--------------------
All :func:`sensitive_variables` and :func:`sensitive_post_parameters` do is,
respectively, annotate the decorated function with the names of sensitive
diff --git a/docs/howto/index.txt b/docs/howto/index.txt
index f06cd6b627d..89e31928101 100644
--- a/docs/howto/index.txt
+++ b/docs/howto/index.txt
@@ -1,3 +1,4 @@
+===============
"How-to" guides
===============
diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt
index f341482167b..2d9fded5c28 100644
--- a/docs/howto/outputting-csv.txt
+++ b/docs/howto/outputting-csv.txt
@@ -76,7 +76,7 @@ mention:
.. _streaming-csv-files:
Streaming large CSV files
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
When dealing with views that generate very large responses, you might want to
consider using Django's :class:`~django.http.StreamingHttpResponse` instead.
diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt
index 842485adfd3..552035b7c28 100644
--- a/docs/howto/writing-migrations.txt
+++ b/docs/howto/writing-migrations.txt
@@ -9,7 +9,7 @@ migrations, see :doc:`the topic guide `.
.. _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
diff --git a/docs/index.txt b/docs/index.txt
index eee8c680f0a..1a2bc2667ed 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -1,6 +1,3 @@
-
-.. _index:
-
====================
Django documentation
====================
diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt
index c6b3d494ff4..5f44c467b54 100644
--- a/docs/internals/contributing/bugs-and-features.txt
+++ b/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
diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt
index d2e415d986a..211bdf011f3 100644
--- a/docs/internals/contributing/committing-code.txt
+++ b/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.
diff --git a/docs/internals/contributing/localizing.txt b/docs/internals/contributing/localizing.txt
index e59286784ff..e3df902549e 100644
--- a/docs/internals/contributing/localizing.txt
+++ b/docs/internals/contributing/localizing.txt
@@ -9,7 +9,7 @@ and localization infrastructure available to Django applications, described in
the :doc:`i18n documentation `.
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//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` 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
diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt
index 8a59ecd20e7..a52e524f572 100644
--- a/docs/internals/contributing/new-contributors.txt
+++ b/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?**
diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt
index c3a8e1d7656..c121e86b268 100644
--- a/docs/internals/contributing/triaging-tickets.txt
+++ b/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`. 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`. 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
diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt
index 5dfe9c00f9f..805741da6d7 100644
--- a/docs/internals/contributing/writing-code/coding-style.txt
+++ b/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 `_ 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 ` 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`.
diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt
index a3b34c564e3..8b8534e384b 100644
--- a/docs/internals/contributing/writing-code/javascript.txt
+++ b/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 `_.
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.
diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index aad0abf6e76..1c6abbd4732 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/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 `?
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
` 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 `?
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index 31e795ee660..1de6caacb5d 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/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 ``_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 ` 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
diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt
index c7d551f24dd..a7588361f2b 100644
--- a/docs/internals/contributing/writing-code/working-with-git.txt
+++ b/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
`_ 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 `.
Summary
--------
+=======
* Work on GitHub if you can.
* Announce your work on the Trac ticket by linking to your GitHub branch.
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index c48248fb79d..6c4e583866c 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/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 `. 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 ` 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 ` command. This is configured in
diff --git a/docs/internals/index.txt b/docs/internals/index.txt
index 415e6bfeb53..e9c32fe3044 100644
--- a/docs/internals/index.txt
+++ b/docs/internals/index.txt
@@ -1,3 +1,4 @@
+================
Django internals
================
diff --git a/docs/internals/mailing-lists.txt b/docs/internals/mailing-lists.txt
index fc2fa320f01..1ca979fe937 100644
--- a/docs/internals/mailing-lists.txt
+++ b/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.
diff --git a/docs/internals/security.txt b/docs/internals/security.txt
index fe5c02bac5c..7107a105eb7 100644
--- a/docs/internals/security.txt
+++ b/docs/internals/security.txt
@@ -1,5 +1,3 @@
-.. _internals-security:
-
==========================
Django's security policies
==========================
diff --git a/docs/intro/index.txt b/docs/intro/index.txt
index d063fec0479..ab4ae21469d 100644
--- a/docs/intro/index.txt
+++ b/docs/intro/index.txt
@@ -1,3 +1,4 @@
+===============
Getting started
===============
diff --git a/docs/intro/install.txt b/docs/intro/install.txt
index ae6e4bb7a0e..c1348fbe625 100644
--- a/docs/intro/install.txt
+++ b/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 `.
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 `.
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 `.
diff --git a/docs/misc/index.txt b/docs/misc/index.txt
index fb5c026a4d0..6232a26e376 100644
--- a/docs/misc/index.txt
+++ b/docs/misc/index.txt
@@ -1,3 +1,4 @@
+=================================
Meta-documentation and miscellany
=================================
diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt
index dd8a81d800b..2f48c6b3063 100644
--- a/docs/ref/class-based-views/base.txt
+++ b/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
diff --git a/docs/ref/class-based-views/flattened-index.txt b/docs/ref/class-based-views/flattened-index.txt
index 9107d43d8b8..d549cd4245d 100644
--- a/docs/ref/class-based-views/flattened-index.txt
+++ b/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`
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):
diff --git a/docs/ref/class-based-views/generic-date-based.txt b/docs/ref/class-based-views/generic-date-based.txt
index b03e34858ea..16a3ff147e3 100644
--- a/docs/ref/class-based-views/generic-date-based.txt
+++ b/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
MonthArchiveView
-----------------
+================
.. class:: MonthArchiveView
@@ -289,7 +289,7 @@ MonthArchiveView
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
TodayArchiveView
-----------------
+================
.. class:: TodayArchiveView
@@ -551,7 +551,7 @@ TodayArchiveView
name of the new template.
DateDetailView
---------------
+==============
.. class:: DateDetailView
diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt
index 5dc03913193..8f45ce654b0 100644
--- a/docs/ref/class-based-views/generic-display.txt
+++ b/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
Date: {{ now|date }}
ListView
---------
+========
.. class:: django.views.generic.list.ListView
diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt
index d726c0a3cbd..c59870c4f02 100644
--- a/docs/ref/class-based-views/generic-editing.txt
+++ b/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
UpdateView
-----------
+==========
.. class:: django.views.generic.edit.UpdateView
@@ -193,7 +193,7 @@ UpdateView
DeleteView
-----------
+==========
.. class:: django.views.generic.edit.DeleteView
diff --git a/docs/ref/class-based-views/index.txt b/docs/ref/class-based-views/index.txt
index b5ba62dbc34..56708495625 100644
--- a/docs/ref/class-based-views/index.txt
+++ b/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
diff --git a/docs/ref/class-based-views/mixins-date-based.txt b/docs/ref/class-based-views/mixins-date-based.txt
index 020fc918b88..921d3dee0d8 100644
--- a/docs/ref/class-based-views/mixins-date-based.txt
+++ b/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
diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt
index 29e1f05a8ee..2676cbf0bc2 100644
--- a/docs/ref/class-based-views/mixins-editing.txt
+++ b/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
diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt
index 6c4cdadedfa..8b30d91f236 100644
--- a/docs/ref/class-based-views/mixins-multiple-object.txt
+++ b/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
diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt
index 9550c22ed4b..e6fd4ac3f4b 100644
--- a/docs/ref/class-based-views/mixins-simple.txt
+++ b/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
`.
TemplateResponseMixin
----------------------
+=====================
.. class:: django.views.generic.base.TemplateResponseMixin
diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt
index 02c1437526b..d04f5dc5a1f 100644
--- a/docs/ref/class-based-views/mixins-single-object.txt
+++ b/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
diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt
index ed51b5ea8f5..5f8f5a21d42 100644
--- a/docs/ref/clickjacking.txt
+++ b/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``.
diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index e4c31731d50..66906d5ddc3 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -1,3 +1,4 @@
+=======================
``django.contrib.auth``
=======================
diff --git a/docs/ref/contrib/gis/forms-api.txt b/docs/ref/contrib/gis/forms-api.txt
index b9c0c1dbe44..c2593acba62 100644
--- a/docs/ref/contrib/gis/forms-api.txt
+++ b/docs/ref/contrib/gis/forms-api.txt
@@ -18,7 +18,7 @@ In addition to the regular :ref:`form 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``
diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt
index 4ac7a4bc723..282fe55a388 100644
--- a/docs/ref/contrib/gis/functions.txt
+++ b/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)
diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt
index 86a85cb05ff..617d45f4812 100644
--- a/docs/ref/contrib/gis/install/geolibs.txt
+++ b/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`
diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt
index f30a3d74dc2..cf49ca7de17 100644
--- a/docs/ref/contrib/gis/install/index.txt
+++ b/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 `_ 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 ` on your system.
diff --git a/docs/ref/contrib/gis/install/spatialite.txt b/docs/ref/contrib/gis/install/spatialite.txt
index d950472e8a5..cf5710c3952 100644
--- a/docs/ref/contrib/gis/install/spatialite.txt
+++ b/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` 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
diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt
index fccbdce35f3..d5fe84ebd60 100644
--- a/docs/ref/contrib/gis/model-api.txt
+++ b/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]_
diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt
index 456f9c32b36..b50f276522e 100644
--- a/docs/ref/contrib/gis/testing.txt
+++ b/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 CREATEDB NOSUPERUSER NOCREATEROLE;
Create database superuser
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
This may be done at the time the user is created, for example::
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index 89365442c07..9a09c937741 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -695,7 +695,7 @@ GeoDjango extends :doc:`Django's admin application `
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.
diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt
index 8accfe326e6..66b15d70f3a 100644
--- a/docs/ref/contrib/humanize.txt
+++ b/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 ` 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 ` 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.
diff --git a/docs/ref/contrib/postgres/aggregates.txt b/docs/ref/contrib/postgres/aggregates.txt
index d4c5f028f6d..f9d222c930d 100644
--- a/docs/ref/contrib/postgres/aggregates.txt
+++ b/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::
diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt
index cb6f15acc56..af41666aa73 100644
--- a/docs/ref/contrib/postgres/fields.txt
+++ b/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
]>
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))
]>
@@ -683,7 +684,7 @@ contains
.. fieldlookup:: rangefield.contained_by
contained_by
-''''''''''''
+^^^^^^^^^^^^
>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
]>
@@ -707,7 +708,7 @@ contained_by
.. fieldlookup:: rangefield.overlap
overlap
-'''''''
+^^^^^^^
>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
]>
@@ -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`.
diff --git a/docs/ref/contrib/postgres/forms.txt b/docs/ref/contrib/postgres/forms.txt
index 431cf9c802a..288c826f93f 100644
--- a/docs/ref/contrib/postgres/forms.txt
+++ b/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)
diff --git a/docs/ref/contrib/postgres/functions.txt b/docs/ref/contrib/postgres/functions.txt
index f4abdc2c178..25dac99e4de 100644
--- a/docs/ref/contrib/postgres/functions.txt
+++ b/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()
diff --git a/docs/ref/contrib/postgres/index.txt b/docs/ref/contrib/postgres/index.txt
index 29847c3f99b..fe5b3be2abf 100644
--- a/docs/ref/contrib/postgres/index.txt
+++ b/docs/ref/contrib/postgres/index.txt
@@ -1,3 +1,4 @@
+===========================
``django.contrib.postgres``
===========================
diff --git a/docs/ref/contrib/postgres/operations.txt b/docs/ref/contrib/postgres/operations.txt
index 79c2021c393..81ecb6acb2d 100644
--- a/docs/ref/contrib/postgres/operations.txt
+++ b/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()
diff --git a/docs/ref/contrib/postgres/validators.txt b/docs/ref/contrib/postgres/validators.txt
index f35a40dd27f..21a1935f559 100644
--- a/docs/ref/contrib/postgres/validators.txt
+++ b/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)
diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt
index d6824af18c4..6c9b93f1d67 100644
--- a/docs/ref/files/file.txt
+++ b/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:
diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt
index be9c554341c..6bbb197c0c0 100644
--- a/docs/ref/files/storage.txt
+++ b/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
diff --git a/docs/ref/files/uploads.txt b/docs/ref/files/uploads.txt
index 028e7a6875c..9bc508781fe 100644
--- a/docs/ref/files/uploads.txt
+++ b/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:
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index c36f19ca2b7..631fe1ea54d 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -13,7 +13,7 @@ The Forms API
.. _ref-forms-api-bound-unbound:
Bound and unbound forms
------------------------
+=======================
A :class:`Form` instance is either **bound** to a set of data, or **unbound**.
@@ -69,7 +69,7 @@ another :class:`Form` instance. There is no way to change data in a
should consider its data immutable, whether it has data or not.
Using forms to validate data
-----------------------------
+============================
.. method:: Form.clean()
@@ -201,7 +201,7 @@ This includes ``ValidationError``\s that are raised in :meth:`Form.clean()
"...") `.
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::
Comment:
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::
'
Username:
'
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::
``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 ``