Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.5.x] Added missing markup to docs.

Backport of 93cffc3 from master.
  • Loading branch information...
commit f7ca464039b4f21705a8a7074f6c542c3e4937b4 1 parent 1363b41
@timgraham timgraham authored
Showing with 164 additions and 148 deletions.
  1. +3 −3 docs/howto/custom-model-fields.txt
  2. +1 −1  docs/internals/deprecation.txt
  3. +2 −2 docs/intro/tutorial03.txt
  4. +8 −8 docs/ref/class-based-views/mixins-date-based.txt
  5. +1 −1  docs/ref/class-based-views/mixins-single-object.txt
  6. +14 −13 docs/ref/clickjacking.txt
  7. +1 −1  docs/ref/contrib/admin/actions.txt
  8. +1 −1  docs/ref/contrib/csrf.txt
  9. +2 −2 docs/ref/contrib/gis/gdal.txt
  10. +2 −2 docs/ref/contrib/sitemaps.txt
  11. +1 −1  docs/ref/django-admin.txt
  12. +2 −2 docs/ref/models/fields.txt
  13. +1 −1  docs/ref/settings.txt
  14. +1 −1  docs/ref/template-response.txt
  15. +3 −3 docs/ref/urls.txt
  16. +1 −1  docs/releases/1.2-alpha-1.txt
  17. +4 −4 docs/releases/1.2.txt
  18. +1 −1  docs/releases/1.3-alpha-1.txt
  19. +3 −3 docs/releases/1.3-beta-1.txt
  20. +1 −1  docs/releases/1.3.txt
  21. +1 −1  docs/releases/1.4-alpha-1.txt
  22. +1 −1  docs/releases/1.4-beta-1.txt
  23. +1 −1  docs/releases/1.4.txt
  24. +9 −6 docs/releases/1.5-alpha-1.txt
  25. +9 −6 docs/releases/1.5-beta-1.txt
  26. +12 −9 docs/releases/1.5.txt
  27. +29 −27 docs/topics/auth/customizing.txt
  28. +3 −3 docs/topics/auth/passwords.txt
  29. +1 −1  docs/topics/class-based-views/mixins.txt
  30. +20 −16 docs/topics/db/aggregation.txt
  31. +2 −3 docs/topics/db/managers.txt
  32. +1 −1  docs/topics/db/optimization.txt
  33. +2 −2 docs/topics/db/queries.txt
  34. +3 −2 docs/topics/http/shortcuts.txt
  35. +6 −6 docs/topics/logging.txt
  36. +6 −6 docs/topics/serialization.txt
  37. +5 −5 docs/topics/testing/overview.txt
View
6 docs/howto/custom-model-fields.txt
@@ -222,9 +222,9 @@ parameters:
* :attr:`~django.db.models.Field.db_tablespace`: Only for index creation, if the
backend supports :doc:`tablespaces </topics/db/tablespaces>`. You can usually
ignore this option.
-* ``auto_created``: True if the field was
- automatically created, as for the `OneToOneField` used by model
- inheritance. For advanced use only.
+* ``auto_created``: ``True`` if the field was automatically created, as for the
+ :class:`~django.db.models.OneToOneField` used by model inheritance. For
+ advanced use only.
All of the options without an explanation in the above list have the same
meaning they do for normal Django fields. See the :doc:`field documentation
View
2  docs/internals/deprecation.txt
@@ -111,7 +111,7 @@ See the :doc:`Django 1.3 release notes</releases/1.3>` for more details on
these changes.
* Starting Django without a :setting:`SECRET_KEY` will result in an exception
- rather than a `DeprecationWarning`. (This is accelerated from the usual
+ rather than a ``DeprecationWarning``. (This is accelerated from the usual
deprecation path; see the :doc:`Django 1.4 release notes</releases/1.4>`.)
* The ``mod_python`` request handler will be removed. The ``mod_wsgi``
View
4 docs/intro/tutorial03.txt
@@ -107,7 +107,7 @@ with::
url(r'^admin/', include(admin.site.urls)),
)
-You have now wired an `index` view into the URLconf. Go to
+You have now wired an ``index`` view into the URLconf. Go to
http://localhost:8000/polls/ in your browser, and you should see the text
"*Hello, world. You're at the poll index.*", which you defined in the
``index`` view.
@@ -119,7 +119,7 @@ At this point, it's worth reviewing what these arguments are for.
:func:`~django.conf.urls.url` argument: regex
---------------------------------------------
-The term `regex` is a commonly used short form meaning `regular expression`,
+The term "regex" is a commonly used short form meaning "regular expression",
which is a syntax for matching patterns in strings, or in this case, url
patterns. Django starts at the first regular expression and makes its way down
the list, comparing the requested URL against each regular expression until it
View
16 docs/ref/class-based-views/mixins-date-based.txt
@@ -35,8 +35,8 @@ YearMixin
Tries the following sources, in order:
* The value of the :attr:`YearMixin.year` attribute.
- * The value of the `year` argument captured in the URL pattern.
- * The value of the `year` GET query argument.
+ * The value of the ``year`` argument captured in the URL pattern.
+ * The value of the ``year`` ``GET`` query argument.
Raises a 404 if no valid year specification can be found.
@@ -87,8 +87,8 @@ MonthMixin
Tries the following sources, in order:
* The value of the :attr:`MonthMixin.month` attribute.
- * The value of the `month` argument captured in the URL pattern.
- * The value of the `month` GET query argument.
+ * The value of the ``month`` argument captured in the URL pattern.
+ * The value of the ``month`` ``GET`` query argument.
Raises a 404 if no valid month specification can be found.
@@ -139,8 +139,8 @@ DayMixin
Tries the following sources, in order:
* The value of the :attr:`DayMixin.day` attribute.
- * The value of the `day` argument captured in the URL pattern.
- * The value of the `day` GET query argument.
+ * The value of the ``day`` argument captured in the URL pattern.
+ * The value of the ``day`` ``GET`` query argument.
Raises a 404 if no valid day specification can be found.
@@ -192,8 +192,8 @@ WeekMixin
Tries the following sources, in order:
* The value of the :attr:`WeekMixin.week` attribute.
- * The value of the `week` argument captured in the URL pattern
- * The value of the `week` GET query argument.
+ * The value of the ``week`` argument captured in the URL pattern
+ * The value of the ``week`` ``GET`` query argument.
Raises a 404 if no valid week specification can be found.
View
2  docs/ref/class-based-views/mixins-single-object.txt
@@ -63,7 +63,7 @@ SingleObjectMixin
this view will display. By default, :meth:`get_queryset` returns the
value of the :attr:`queryset` attribute if it is set, otherwise
it constructs a :class:`~django.db.models.query.QuerySet` by calling
- the `all()` method on the :attr:`model` attribute's default manager.
+ the ``all()`` method on the :attr:`model` attribute's default manager.
.. method:: get_context_object_name(obj)
View
27 docs/ref/clickjacking.txt
@@ -33,10 +33,10 @@ Preventing clickjacking
Modern browsers honor the `X-Frame-Options`_ HTTP header that indicates whether
or not a resource is allowed to load within a frame or iframe. If the response
-contains the header with a value of SAMEORIGIN then the browser will only load
-the resource in a frame if the request originated from the same site. If the
-header is set to DENY then the browser will block the resource from loading in a
-frame no matter which site made the request.
+contains the header with a value of ``SAMEORIGIN`` then the browser will only
+load the resource in a frame if the request originated from the same site. If
+the header is set to ``DENY`` then the browser will block the resource from
+loading in a frame no matter which site made the request.
.. _X-Frame-Options: https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header
@@ -64,15 +64,16 @@ To set the same X-Frame-Options value for all responses in your site, add
...
)
-By default, the middleware will set the X-Frame-Options header to SAMEORIGIN for
-every outgoing ``HttpResponse``. If you want DENY instead, set the
-:setting:`X_FRAME_OPTIONS` setting::
+
+By default, the middleware will set the ``X-Frame-Options`` header to
+``SAMEORIGIN`` for every outgoing ``HttpResponse``. If you want ``DENY``
+instead, set the :setting:`X_FRAME_OPTIONS` setting::
X_FRAME_OPTIONS = 'DENY'
When using the middleware there may be some views where you do **not** want the
-X-Frame-Options header set. For those cases, you can use a view decorator that
-tells the middleware not to set the header::
+``X-Frame-Options`` header set. For those cases, you can use a view decorator
+that tells the middleware not to set the header::
from django.http import HttpResponse
from django.views.decorators.clickjacking import xframe_options_exempt
@@ -85,7 +86,7 @@ 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
+To set the ``X-Frame-Options`` header on a per view basis, Django provides these
decorators::
from django.http import HttpResponse
@@ -106,8 +107,8 @@ a decorator overrides the middleware.
Limitations
===========
-The `X-Frame-Options` header will only protect against clickjacking in a modern
-browser. Older browsers will quietly ignore the header and need `other
+The ``X-Frame-Options`` header will only protect against clickjacking in a
+modern browser. Older browsers will quietly ignore the header and need `other
clickjacking prevention techniques`_.
Browsers that support X-Frame-Options
@@ -122,7 +123,7 @@ Browsers that support X-Frame-Options
See also
~~~~~~~~
-A `complete list`_ of browsers supporting X-Frame-Options.
+A `complete list`_ of browsers supporting ``X-Frame-Options``.
.. _complete list: https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header#Browser_compatibility
.. _other clickjacking prevention techniques: http://en.wikipedia.org/wiki/Clickjacking#Prevention
View
2  docs/ref/contrib/admin/actions.txt
@@ -175,7 +175,7 @@ That's easy enough to do::
make_published.short_description = "Mark selected stories as published"
Notice first that we've moved ``make_published`` into a method and renamed the
-`modeladmin` parameter to `self`, and second that we've now put the string
+``modeladmin`` parameter to ``self``, and second that we've now put the string
``'make_published'`` in ``actions`` instead of a direct function reference. This
tells the :class:`ModelAdmin` to look up the action as a method.
View
2  docs/ref/contrib/csrf.txt
@@ -181,7 +181,7 @@ protecting the CSRF token from being sent to other domains.
correctly on that version. Make sure you are running at least jQuery 1.5.1.
You can use `settings.crossDomain <http://api.jquery.com/jQuery.ajax>`_ in
-jQuery 1.5 and newer in order to replace the `sameOrigin` logic above:
+jQuery 1.5 and newer in order to replace the ``sameOrigin`` logic above:
.. code-block:: javascript
View
4 docs/ref/contrib/gis/gdal.txt
@@ -634,8 +634,8 @@ systems and coordinate transformation::
or any other input accepted by :class:`SpatialReference` (including
spatial reference WKT and PROJ.4 strings, or an integer SRID).
By default nothing is returned and the geometry is transformed in-place.
- However, if the `clone` keyword is set to ``True`` then a transformed clone
- of this geometry is returned instead.
+ However, if the ``clone`` keyword is set to ``True`` then a transformed
+ clone of this geometry is returned instead.
.. method:: intersects(other)
View
4 docs/ref/contrib/sitemaps.txt
@@ -462,8 +462,8 @@ cron script, or some other scheduled task. The function makes an HTTP request
to Google's servers, so you may not want to introduce that network overhead
each time you call ``save()``.
-Pinging Google via `manage.py`
-------------------------------
+Pinging Google via ``manage.py``
+--------------------------------
.. django-admin:: ping_google
View
2  docs/ref/django-admin.txt
@@ -1326,7 +1326,7 @@ For example, to dump data from the database with the alias ``master``::
.. django-admin-option:: --exclude
Exclude a specific application from the applications whose contents is
-output. For example, to specifically exclude the `auth` application from
+output. For example, to specifically exclude the ``auth`` application from
the output of dumpdata, you would call::
django-admin.py dumpdata --exclude=auth
View
4 docs/ref/models/fields.txt
@@ -858,8 +858,8 @@ widget for this field is a :class:`~django.forms.NullBooleanSelect`.
.. class:: PositiveIntegerField([**options])
-Like an :class:`IntegerField`, but must be either positive or zero (`0`).
-The value `0` is accepted for backward compatibility reasons.
+Like an :class:`IntegerField`, but must be either positive or zero (``0``).
+The value ``0`` is accepted for backward compatibility reasons.
``PositiveSmallIntegerField``
-----------------------------
View
2  docs/ref/settings.txt
@@ -1420,7 +1420,7 @@ Example: ``"http://media.example.com/"``
MESSAGE_LEVEL
-------------
-Default: `messages.INFO`
+Default: ``messages.INFO``
Sets the minimum message level that will be recorded by the messages
framework. See the :doc:`messages documentation </ref/contrib/messages>` for
View
2  docs/ref/template-response.txt
@@ -120,7 +120,7 @@ Methods
rendered :class:`~django.template.response.SimpleTemplateResponse`
instance.
- If the callback returns a value that is not `None`, this will be
+ If the callback returns a value that is not ``None``, this will be
used as the response instead of the original response object (and
will be passed to the next post rendering callback etc.)
View
6 docs/ref/urls.txt
@@ -31,12 +31,12 @@ The ``optional_dictionary`` and ``optional_name`` parameters are described in
:ref:`Passing extra options to view functions <views-extra-options>`.
.. note::
- Because `patterns()` is a function call, it accepts a maximum of 255
+ Because ``patterns()`` is a function call, it accepts a maximum of 255
arguments (URL patterns, in this case). This is a limit for all Python
function calls. This is rarely a problem in practice, because you'll
- typically structure your URL patterns modularly by using `include()`
+ typically structure your URL patterns modularly by using ``include()``
sections. However, on the off-chance you do hit the 255-argument limit,
- realize that `patterns()` returns a Python list, so you can split up the
+ realize that ``patterns()`` returns a Python list, so you can split up the
construction of the list.
::
View
2  docs/releases/1.2-alpha-1.txt
@@ -428,7 +428,7 @@ Support for multiple databases
Django 1.2 adds the ability to use :doc:`more than one database
</topics/db/multi-db>` in your Django project. Queries can be
-issued at a specific database with the `using()` method on
+issued at a specific database with the ``using()`` method on
querysets; individual objects can be saved to a specific database
by providing a ``using`` argument when you save the instance.
View
8 docs/releases/1.2.txt
@@ -123,9 +123,9 @@ Support for multiple databases
Django 1.2 adds the ability to use :doc:`more than one database
</topics/db/multi-db>` in your Django project. Queries can be issued at a
-specific database with the `using()` method on ``QuerySet`` objects. Individual
-objects can be saved to a specific database by providing a ``using`` argument
-when you call ``save()``.
+specific database with the ``using()`` method on ``QuerySet`` objects.
+Individual objects can be saved to a specific database by providing a ``using``
+argument when you call ``save()``.
Model validation
----------------
@@ -765,7 +765,7 @@ over the next few release cycles.
Code taking advantage of any of the features below will raise a
``PendingDeprecationWarning`` in Django 1.2. This warning will be
silent by default, but may be turned on using Python's :mod:`warnings`
-module, or by running Python with a ``-Wd`` or `-Wall` flag.
+module, or by running Python with a ``-Wd`` or ``-Wall`` flag.
In Django 1.3, these warnings will become a ``DeprecationWarning``,
which is *not* silent. In Django 1.4 support for these features will
View
2  docs/releases/1.3-alpha-1.txt
@@ -279,7 +279,7 @@ over the next few release cycles.
Code taking advantage of any of the features below will raise a
``PendingDeprecationWarning`` in Django 1.3. This warning will be
silent by default, but may be turned on using Python's :mod:`warnings`
-module, or by running Python with a ``-Wd`` or `-Wall` flag.
+module, or by running Python with a ``-Wd`` or ``-Wall`` flag.
In Django 1.4, these warnings will become a ``DeprecationWarning``,
which is *not* silent. In Django 1.5 support for these features will
View
6 docs/releases/1.3-beta-1.txt
@@ -154,7 +154,7 @@ too few.
In Django 1.3 we're taking a new approach to this problem, implemented
as a pair of changes:
-* The choice list for `USStateField` has changed. Previously, it
+* The choice list for ``USStateField`` has changed. Previously, it
consisted of the 50 U.S. states, the District of Columbia and
U.S. overseas territories. As of Django 1.3 it includes all previous
choices, plus the U.S. Armed Forces postal codes.
@@ -163,7 +163,7 @@ as a pair of changes:
``django.contrib.localflavor.us.models.USPostalCodeField``, has
been added which draws its choices from a list of all postal
abbreviations recognized by the U.S Postal Service. This includes
- all abbreviations recognized by `USStateField`, plus three
+ all abbreviations recognized by ``USStateField``, plus three
independent nations -- the Federated States of Micronesia, the
Republic of the Marshall Islands and the Republic of Palau -- which
are serviced under treaty by the U.S. postal system. A new form
@@ -176,7 +176,7 @@ territories, and other locations serviced by the U.S. postal
system. Consult the ``django.contrib.localflavor`` documentation
for more details.
-The change to `USStateField` is technically backwards-incompatible for
+The change to ``USStateField`` is technically backwards-incompatible for
users who expect this field to exclude Armed Forces locations. If you
need to support U.S. mailing addresses without Armed Forces locations,
see the list of choice tuples available in the localflavor
View
2  docs/releases/1.3.txt
@@ -664,7 +664,7 @@ over the next few release cycles.
Code taking advantage of any of the features below will raise a
``PendingDeprecationWarning`` in Django 1.3. This warning will be
silent by default, but may be turned on using Python's :mod:`warnings`
-module, or by running Python with a ``-Wd`` or `-Wall` flag.
+module, or by running Python with a ``-Wd`` or ``-Wall`` flag.
In Django 1.4, these warnings will become a ``DeprecationWarning``,
which is *not* silent. In Django 1.5 support for these features will
View
2  docs/releases/1.4-alpha-1.txt
@@ -877,7 +877,7 @@ removed.
The ``open`` method of the base Storage class took an obscure parameter
``mixin`` which allowed you to dynamically change the base classes of the
returned file object. This has been removed. In the rare case you relied on the
-`mixin` parameter, you can easily achieve the same by overriding the `open`
+``mixin`` parameter, you can easily achieve the same by overriding the ``open``
method, e.g.::
from django.core.files import File
View
2  docs/releases/1.4-beta-1.txt
@@ -945,7 +945,7 @@ removed.
The ``open`` method of the base Storage class took an obscure parameter
``mixin`` which allowed you to dynamically change the base classes of the
returned file object. This has been removed. In the rare case you relied on the
-`mixin` parameter, you can easily achieve the same by overriding the `open`
+``mixin`` parameter, you can easily achieve the same by overriding the ``open``
method, e.g.::
from django.core.files import File
View
2  docs/releases/1.4.txt
@@ -1039,7 +1039,7 @@ removed.
The ``open`` method of the base Storage class used to take an obscure parameter
``mixin`` that allowed you to dynamically change the base classes of the
returned file object. This has been removed. In the rare case you relied on the
-`mixin` parameter, you can easily achieve the same by overriding the `open`
+``mixin`` parameter, you can easily achieve the same by overriding the ``open``
method, like this::
from django.core.files import File
View
15 docs/releases/1.5-alpha-1.txt
@@ -227,7 +227,9 @@ GeoDjango
:meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods
(so-called linear referencing).
-* The wkb and hex properties of `GEOSGeometry` objects preserve the Z dimension.
+* The ``wkb`` and ``hex`` properties of
+ :class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z
+ dimension.
* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been
dropped.
@@ -283,8 +285,8 @@ Django 1.5 also includes several smaller improvements worth noting:
* An instance of :class:`~django.core.urlresolvers.ResolverMatch` is stored on
the request as ``resolver_match``.
-* By default, all logging messages reaching the `django` logger when
- :setting:`DEBUG` is `True` are sent to the console (unless you redefine the
+* By default, all logging messages reaching the ``django`` logger when
+ :setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the
logger in your :setting:`LOGGING` setting).
* When using :class:`~django.template.RequestContext`, it is now possible to
@@ -301,8 +303,9 @@ Django 1.5 also includes several smaller improvements worth noting:
whenever a user fails to login successfully. See
:data:`~django.contrib.auth.signals.user_login_failed`
-* The loaddata management command now supports an `ignorenonexistent` option to
- ignore data for fields that no longer exist.
+* The loaddata management command now supports an
+ :djadminopt:`--ignorenonexistent` option to ignore data for fields that no
+ longer exist.
* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
:meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow
@@ -556,7 +559,7 @@ Miscellaneous
* Uploaded files are no longer created as executable by default. If you need
them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your
- needs. The new default value is `0666` (octal) and the current umask value
+ needs. The new default value is ``0666`` (octal) and the current umask value
is first masked out.
* The :ref:`F() expressions <query-expressions>` supported bitwise operators by
View
15 docs/releases/1.5-beta-1.txt
@@ -225,7 +225,9 @@ GeoDjango
:meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods
(so-called linear referencing).
-* The wkb and hex properties of `GEOSGeometry` objects preserve the Z dimension.
+* The ``wkb`` and ``hex`` properties of
+ :class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z
+ dimension.
* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been
dropped.
@@ -281,8 +283,8 @@ Django 1.5 also includes several smaller improvements worth noting:
* An instance of :class:`~django.core.urlresolvers.ResolverMatch` is stored on
the request as ``resolver_match``.
-* By default, all logging messages reaching the `django` logger when
- :setting:`DEBUG` is `True` are sent to the console (unless you redefine the
+* By default, all logging messages reaching the ``django`` logger when
+ :setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the
logger in your :setting:`LOGGING` setting).
* When using :class:`~django.template.RequestContext`, it is now possible to
@@ -299,8 +301,9 @@ Django 1.5 also includes several smaller improvements worth noting:
whenever a user fails to login successfully. See
:data:`~django.contrib.auth.signals.user_login_failed`
-* The loaddata management command now supports an `ignorenonexistent` option to
- ignore data for fields that no longer exist.
+* The loaddata management command now supports an
+ :djadminopt:`--ignorenonexistent` option to ignore data for fields that no
+ longer exist.
* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
:meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow
@@ -595,7 +598,7 @@ Miscellaneous
* Uploaded files are no longer created as executable by default. If you need
them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your
- needs. The new default value is `0666` (octal) and the current umask value
+ needs. The new default value is ``0666`` (octal) and the current umask value
is first masked out.
* The :ref:`F() expressions <query-expressions>` supported bitwise operators by
View
21 docs/releases/1.5.txt
@@ -146,9 +146,9 @@ keyword argument ``update_fields``. By using this argument it is possible to
save only a select list of model's fields. This can be useful for performance
reasons or when trying to avoid overwriting concurrent changes.
-Deferred instances (those loaded by .only() or .defer()) will automatically
-save just the loaded fields. If any field is set manually after load, that
-field will also get updated on save.
+Deferred instances (those loaded by ``.only()`` or ``.defer()``) will
+automatically save just the loaded fields. If any field is set manually after
+load, that field will also get updated on save.
See the :meth:`Model.save() <django.db.models.Model.save()>` documentation for
more details.
@@ -224,7 +224,9 @@ GeoDjango
:meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods
(so-called linear referencing).
-* The wkb and hex properties of `GEOSGeometry` objects preserve the Z dimension.
+* The ``wkb`` and ``hex`` properties of
+ :class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z
+ dimension.
* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been
dropped.
@@ -294,8 +296,8 @@ Django 1.5 also includes several smaller improvements worth noting:
* An instance of :class:`~django.core.urlresolvers.ResolverMatch` is stored on
the request as ``resolver_match``.
-* By default, all logging messages reaching the `django` logger when
- :setting:`DEBUG` is `True` are sent to the console (unless you redefine the
+* By default, all logging messages reaching the ``django`` logger when
+ :setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the
logger in your :setting:`LOGGING` setting).
* When using :class:`~django.template.RequestContext`, it is now possible to
@@ -312,8 +314,9 @@ Django 1.5 also includes several smaller improvements worth noting:
whenever a user fails to login successfully. See
:data:`~django.contrib.auth.signals.user_login_failed`
-* The loaddata management command now supports an `ignorenonexistent` option to
- ignore data for fields that no longer exist.
+* The loaddata management command now supports an
+ :djadminopt:`--ignorenonexistent` option to ignore data for fields that no
+ longer exist.
* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
:meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow
@@ -664,7 +667,7 @@ Miscellaneous
* Uploaded files are no longer created as executable by default. If you need
them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your
- needs. The new default value is `0666` (octal) and the current umask value
+ needs. The new default value is ``0666`` (octal) and the current umask value
is first masked out.
* The :ref:`F() expressions <query-expressions>` supported bitwise operators by
View
56 docs/topics/auth/customizing.txt
@@ -97,12 +97,14 @@ the time, it'll just look like this::
class MyBackend(object):
def authenticate(self, username=None, password=None):
# Check the username/password and return a User.
+ ...
But it could also authenticate a token, like so::
class MyBackend(object):
def authenticate(self, token=None):
# Check the token and return a User.
+ ...
Either way, ``authenticate`` should check the credentials it gets, and it
should return a ``User`` object that matches those credentials, if the
@@ -177,9 +179,7 @@ The simple backend above could implement permissions for the magic admin
fairly simply::
class SettingsBackend(object):
-
- # ...
-
+ ...
def has_perm(self, user_obj, perm, obj=None):
if user_obj.username == settings.ADMIN_LOGIN:
return True
@@ -476,7 +476,7 @@ Django expects your custom User model to meet some minimum requirements.
The easiest way to construct a compliant custom User model is to inherit from
:class:`~django.contrib.auth.models.AbstractBaseUser`.
:class:`~django.contrib.auth.models.AbstractBaseUser` provides the core
-implementation of a `User` model, including hashed passwords and tokenized
+implementation of a ``User`` model, including hashed passwords and tokenized
password resets. You must then provide some key implementation details:
.. currentmodule:: django.contrib.auth
@@ -491,7 +491,7 @@ password resets. You must then provide some key implementation details:
identifier. The field *must* be unique (i.e., have ``unique=True``
set in it's definition).
- In the following example, the field `identifier` is used
+ In the following example, the field ``identifier`` is used
as the identifying field::
class MyUser(AbstractBaseUser):
@@ -599,11 +599,11 @@ The following methods are available on any subclass of
:meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` has
been called for this user.
-You should also define a custom manager for your User model. If your User
-model defines `username` and `email` fields the same as Django's default User,
-you can just install Django's
-:class:`~django.contrib.auth.models.UserManager`; however, if your User model
-defines different fields, you will need to define a custom manager that
+You should also define a custom manager for your ``User`` model. If your
+``User`` model defines ``username`` and ``email`` fields the same as Django's
+default ``User``, you can just install Django's
+:class:`~django.contrib.auth.models.UserManager`; however, if your ``User``
+model defines different fields, you will need to define a custom manager that
extends :class:`~django.contrib.auth.models.BaseUserManager` providing two
additional methods:
@@ -611,26 +611,28 @@ additional methods:
.. method:: models.CustomUserManager.create_user(*username_field*, password=None, \**other_fields)
- The prototype of `create_user()` should accept the username field,
+ The prototype of ``create_user()`` should accept the username field,
plus all required fields as arguments. For example, if your user model
- uses `email` as the username field, and has `date_of_birth` as a required
- fields, then create_user should be defined as::
+ uses ``email`` as the username field, and has ``date_of_birth`` as a
+ required fields, then ``create_user`` should be defined as::
def create_user(self, email, date_of_birth, password=None):
# create user here
+ ...
.. method:: models.CustomUserManager.create_superuser(*username_field*, password, \**other_fields)
- The prototype of `create_superuser()` should accept the username field,
- plus all required fields as arguments. For example, if your user model
- uses `email` as the username field, and has `date_of_birth` as a required
- fields, then create_superuser should be defined as::
+ The prototype of ``create_superuser()`` should accept the username
+ field, plus all required fields as arguments. For example, if your user
+ model uses ``email`` as the username field, and has ``date_of_birth``
+ as a required fields, then ``create_superuser`` should be defined as::
def create_superuser(self, email, date_of_birth, password):
# create superuser here
+ ...
- Unlike `create_user()`, `create_superuser()` *must* require the caller
- to provider a password.
+ Unlike ``create_user()``, ``create_superuser()`` *must* require the
+ caller to provider a password.
:class:`~django.contrib.auth.models.BaseUserManager` provides the following
utility methods:
@@ -699,7 +701,7 @@ auth views.
* :class:`~django.contrib.auth.forms.PasswordResetForm`
Assumes that the user model has an integer primary key, has a field named
- `email` that can be used to identify the user, and a boolean field
+ ``email`` that can be used to identify the user, and a boolean field
named `is_active` to prevent password resets for inactive users.
* :class:`~django.contrib.auth.forms.SetPasswordForm`
@@ -715,8 +717,8 @@ auth views.
Works with any subclass of :class:`~django.contrib.auth.models.AbstractBaseUser`
-Custom users and django.contrib.admin
--------------------------------------
+Custom users and :mod:`django.contrib.admin`
+--------------------------------------------
If you want your custom User model to also work with Admin, your User model must
define some additional attributes and methods. These methods allow the admin to
@@ -726,21 +728,21 @@ control access of the User to admin content:
.. attribute:: is_staff
- Returns True if the user is allowed to have access to the admin site.
+ Returns ``True`` if the user is allowed to have access to the admin site.
.. attribute:: is_active
- Returns True if the user account is currently active.
+ Returns ``True`` if the user account is currently active.
.. method:: has_perm(perm, obj=None):
- Returns True if the user has the named permission. If `obj` is
+ Returns ``True`` if the user has the named permission. If ``obj`` is
provided, the permission needs to be checked against a specific object
instance.
.. method:: has_module_perms(app_label):
- Returns True if the user has permission to access models in
+ Returns ``True`` if the user has permission to access models in
the given app.
You will also need to register your custom User model with the admin. If
@@ -905,7 +907,7 @@ A full example
Here is an example of an admin-compliant custom user app. This user model uses
an email address as the username, and has a required date of birth; it
-provides no permission checking, beyond a simple `admin` flag on the user
+provides no permission checking, beyond a simple ``admin`` flag on the user
account. This model would be compatible with all the built-in auth forms and
views, except for the User creation forms. This example illustrates how most of
the components work together, but is not intended to be copied directly into
View
6 docs/topics/auth/passwords.txt
@@ -105,9 +105,9 @@ algorithm.
There are several other implementations that allow bcrypt to be
used with Django. Django's bcrypt support is NOT directly
compatible with these. To upgrade, you will need to modify the
- hashes in your database to be in the form `bcrypt$(raw bcrypt
- output)`. For example:
- `bcrypt$$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy`.
+ hashes in your database to be in the form ``bcrypt$(raw bcrypt
+ output)``. For example:
+ ``bcrypt$$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy``.
Increasing the work factor
--------------------------
View
2  docs/topics/class-based-views/mixins.txt
@@ -13,7 +13,7 @@ but some of it you may want to use separately. For instance, you may
want to write a view that renders a template to make the HTTP
response, but you can't use
:class:`~django.views.generic.base.TemplateView`; perhaps you need to
-render a template only on `POST`, with `GET` doing something else
+render a template only on ``POST``, with ``GET`` doing something else
entirely. While you could use
:class:`~django.template.response.TemplateResponse` directly, this
will likely result in duplicate code.
View
36 docs/topics/db/aggregation.txt
@@ -43,7 +43,9 @@ used to track the inventory for a series of online bookstores:
Cheat sheet
===========
-In a hurry? Here's how to do common aggregate queries, assuming the models above::
+In a hurry? Here's how to do common aggregate queries, assuming the models above:
+
+.. code-block:: python
# Total number of books.
>>> Book.objects.count()
@@ -140,8 +142,10 @@ will be annotated with the specified values.
The syntax for these annotations is identical to that used for the
``aggregate()`` clause. Each argument to ``annotate()`` describes an
-aggregate that is to be calculated. For example, to annotate Books with
-the number of authors::
+aggregate that is to be calculated. For example, to annotate books with
+the number of authors:
+
+.. code-block:: python
# Build an annotated queryset
>>> q = Book.objects.annotate(Count('authors'))
@@ -190,8 +194,8 @@ you could use the annotation::
>>> Store.objects.annotate(min_price=Min('books__price'), max_price=Max('books__price'))
-This tells Django to retrieve the Store model, join (through the
-many-to-many relationship) with the Book model, and aggregate on the
+This tells Django to retrieve the ``Store`` model, join (through the
+many-to-many relationship) with the ``Book`` model, and aggregate on the
price field of the book model to produce a minimum and maximum value.
The same rules apply to the ``aggregate()`` clause. If you wanted to
@@ -215,32 +219,32 @@ querying can include traversing "reverse" relationships. The lowercase name
of related models and double-underscores are used here too.
For example, we can ask for all publishers, annotated with their respective
-total book stock counters (note how we use `'book'` to specify the
-Publisher->Book reverse foreign key hop)::
+total book stock counters (note how we use ``'book'`` to specify the
+``Publisher`` -> ``Book`` reverse foreign key hop)::
>>> from django.db.models import Count, Min, Sum, Max, Avg
>>> Publisher.objects.annotate(Count('book'))
-(Every Publisher in the resulting QuerySet will have an extra attribute called
-``book__count``.)
+(Every ``Publisher`` in the resulting ``QuerySet`` will have an extra attribute
+called ``book__count``.)
We can also ask for the oldest book of any of those managed by every publisher::
>>> Publisher.objects.aggregate(oldest_pubdate=Min('book__pubdate'))
(The resulting dictionary will have a key called ``'oldest_pubdate'``. If no
-such alias was specified, it would be the rather long ``'book__pubdate__min'``.)
+such alias were specified, it would be the rather long ``'book__pubdate__min'``.)
This doesn't apply just to foreign keys. It also works with many-to-many
relations. For example, we can ask for every author, annotated with the total
number of pages considering all the books he/she has (co-)authored (note how we
-use `'book'` to specify the Author->Book reverse many-to-many hop)::
+use ``'book'`` to specify the ``Author`` -> ``Book`` reverse many-to-many hop)::
>>> Author.objects.annotate(total_pages=Sum('book__pages'))
-(Every Author in the resulting QuerySet will have an extra attribute called
-``total_pages``. If no such alias was specified, it would be the rather long
-``book__pages__sum``.)
+(Every ``Author`` in the resulting ``QuerySet`` will have an extra attribute
+called ``total_pages``. If no such alias were specified, it would be the rather
+long ``book__pages__sum``.)
Or ask for the average rating of all the books written by author(s) we have on
file::
@@ -248,7 +252,7 @@ file::
>>> Author.objects.aggregate(average_rating=Avg('book__rating'))
(The resulting dictionary will have a key called ``'average__rating'``. If no
-such alias was specified, it would be the rather long ``'book__rating__avg'``.)
+such alias were specified, it would be the rather long ``'book__rating__avg'``.)
Aggregations and other QuerySet clauses
=======================================
@@ -308,7 +312,7 @@ and the query::
>>> Publisher.objects.filter(book__rating__gt=3.0).annotate(num_books=Count('book'))
-Both queries will return a list of Publishers that have at least one good
+Both queries will return a list of publishers that have at least one good
book (i.e., a book with a rating exceeding 3.0). However, the annotation in
the first query will provide the total number of all books published by the
publisher; the second query will only include good books in the annotated
View
5 docs/topics/db/managers.txt
@@ -188,7 +188,7 @@ by the default manager.
If the normal plain manager class (:class:`django.db.models.Manager`) is not
appropriate for your circumstances, you can force Django to use the same class
-as the default manager for your model by setting the `use_for_related_fields`
+as the default manager for your model by setting the ``use_for_related_fields``
attribute on the manager class. This is documented fully below_.
.. _below: manager-types_
@@ -366,7 +366,7 @@ it will use :class:`django.db.models.Manager`.
Writing correct Managers for use in automatic Manager instances
---------------------------------------------------------------
-As already suggested by the `django.contrib.gis` example, above, the
+As already suggested by the :mod:`django.contrib.gis` example, above, the
``use_for_related_fields`` feature is primarily for managers that need to
return a custom ``QuerySet`` subclass. In providing this functionality in your
manager, there are a couple of things to remember.
@@ -410,4 +410,3 @@ used in a model, since the attribute's value is processed when the model class
is created and not subsequently reread. Set the attribute on the manager class
when it is first defined, as in the initial example of this section and
everything will work smoothly.
-
View
2  docs/topics/db/optimization.txt
@@ -157,7 +157,7 @@ Doing the following is potentially quite slow:
>>> entry = Entry.objects.get(headline__startswith="News")
-First of all, `headline` is not indexed, which will make the underlying
+First of all, ``headline`` is not indexed, which will make the underlying
database fetch slower.
Second, the lookup doesn't guarantee that only one object will be returned.
View
4 docs/topics/db/queries.txt
@@ -297,8 +297,8 @@ the query - in this case, it will be a
:class:`~django.db.models.query.QuerySet` containing a single element.
If you know there is only one object that matches your query, you can use the
-:meth:`~django.db.models.query.QuerySet.get` method on a `Manager` which
-returns the object directly::
+:meth:`~django.db.models.query.QuerySet.get` method on a
+:class:`~django.db.models.Manager` which returns the object directly::
>>> one_entry = Entry.objects.get(pk=1)
View
5 docs/topics/http/shortcuts.txt
@@ -169,8 +169,9 @@ This example is equivalent to::
* A model: the model's `get_absolute_url()` function will be called.
- * A view name, possibly with arguments: `urlresolvers.reverse()` will
- be used to reverse-resolve the name.
+ * A view name, possibly with arguments: :func:`urlresolvers.reverse
+ <django.core.urlresolvers.reverse>` will be used to reverse-resolve the
+ name.
* A URL, which will be used as-is for the redirect location.
View
12 docs/topics/logging.txt
@@ -308,7 +308,7 @@ This logging configuration does the following things:
* ``simple``, that just outputs the log level name (e.g.,
``DEBUG``) and the log message.
- The `format` string is a normal Python formatting string
+ The ``format`` string is a normal Python formatting string
describing the details that are to be output on each logging
line. The full list of detail that can be output can be
found in the `formatter documentation`_.
@@ -330,7 +330,7 @@ This logging configuration does the following things:
higher) message to ``/dev/null``.
* ``console``, a StreamHandler, which will print any ``DEBUG``
- (or higher) message to stderr. This handler uses the `simple` output
+ (or higher) message to stderr. This handler uses the ``simple`` output
format.
* ``mail_admins``, an AdminEmailHandler, which will email any
@@ -531,7 +531,7 @@ logging module.
This filter is used as follows in the default :setting:`LOGGING`
configuration to ensure that the :class:`AdminEmailHandler` only sends error
- emails to admins when :setting:`DEBUG` is `False`::
+ emails to admins when :setting:`DEBUG` is ``False``::
'filters': {
'require_debug_false': {
@@ -551,7 +551,7 @@ logging module.
.. versionadded:: 1.5
This filter is similar to :class:`RequireDebugFalse`, except that records are
- passed only when :setting:`DEBUG` is `True`.
+ passed only when :setting:`DEBUG` is ``True``.
.. _default-logging-configuration:
@@ -563,8 +563,8 @@ with ``ERROR`` or ``CRITICAL`` level are sent to :class:`AdminEmailHandler`, as
long as the :setting:`DEBUG` setting is set to ``False``.
All messages reaching the ``django`` catch-all logger when :setting:`DEBUG` is
-`True` are sent ot the console. They are simply discarded (sent to
-``NullHandler``) when :setting:`DEBUG` is `False`.
+``True`` are sent to the console. They are simply discarded (sent to
+``NullHandler``) when :setting:`DEBUG` is ``False``.
.. versionchanged:: 1.5
View
12 docs/topics/serialization.txt
@@ -90,11 +90,11 @@ If you only serialize the Restaurant model::
data = serializers.serialize('xml', Restaurant.objects.all())
-the fields on the serialized output will only contain the `serves_hot_dogs`
-attribute. The `name` attribute of the base class will be ignored.
+the fields on the serialized output will only contain the ``serves_hot_dogs``
+attribute. The ``name`` attribute of the base class will be ignored.
-In order to fully serialize your Restaurant instances, you will need to
-serialize the Place models as well::
+In order to fully serialize your ``Restaurant`` instances, you will need to
+serialize the ``Place`` models as well::
all_objects = list(Restaurant.objects.all()) + list(Place.objects.all())
data = serializers.serialize('xml', all_objects)
@@ -343,7 +343,7 @@ When ``use_natural_keys=True`` is specified, Django will use the
type that defines the method.
If you are using :djadmin:`dumpdata` to generate serialized data, you
-use the `--natural` command line flag to generate natural keys.
+use the :djadminopt:`--natural` command line flag to generate natural keys.
.. note::
@@ -362,7 +362,7 @@ Dependencies during serialization
Since natural keys rely on database lookups to resolve references, it
is important that the data exists before it is referenced. You can't make
-a `forward reference` with natural keys -- the data you're referencing
+a "forward reference" with natural keys -- the data you're referencing
must exist before you include a natural key reference to that data.
To accommodate this limitation, calls to :djadmin:`dumpdata` that use
View
10 docs/topics/testing/overview.txt
@@ -965,8 +965,8 @@ This class provides some additional capabilities that can be useful for testing
Web sites.
Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is
-easy: Just change the base class of your test from `'unittest.TestCase'` to
-`'django.test.TestCase'`. All of the standard Python unit test functionality
+easy: Just change the base class of your test from ``'unittest.TestCase'`` to
+``'django.test.TestCase'``. All of the standard Python unit test functionality
will continue to be available, but it will be augmented with some useful
additions, including:
@@ -1002,7 +1002,7 @@ This allows the use of automated test clients other than the
client, to execute a series of functional tests inside a browser and simulate a
real user's actions.
-By default the live server's address is `'localhost:8081'` and the full URL
+By default the live server's address is ``'localhost:8081'`` and the full URL
can be accessed during the tests with ``self.live_server_url``. If you'd like
to change the default address (in the case, for example, where the 8081 port is
already taken) then you may pass a different one to the :djadmin:`test` command
@@ -1109,7 +1109,7 @@ out the `full reference`_ for more details.
(for example, just after clicking a link or submitting a form), you might
need to check that a response is received by Selenium and that the next
page is loaded before proceeding with further test execution.
- Do this, for example, by making Selenium wait until the `<body>` HTML tag
+ Do this, for example, by making Selenium wait until the ``<body>`` HTML tag
is found in the response (requires Selenium > 2.13):
.. code-block:: python
@@ -1126,7 +1126,7 @@ out the `full reference`_ for more details.
The tricky thing here is that there's really no such thing as a "page load,"
especially in modern Web apps that generate HTML dynamically after the
server generates the initial document. So, simply checking for the presence
- of `<body>` in the response might not necessarily be appropriate for all
+ of ``<body>`` in the response might not necessarily be appropriate for all
use cases. Please refer to the `Selenium FAQ`_ and
`Selenium documentation`_ for more information.
Please sign in to comment.
Something went wrong with that request. Please try again.