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_ul()`` -~~~~~~~~~~~ +----------- .. method:: Form.as_ul() @@ -512,7 +512,7 @@ flexibility::
  • ``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 ``