From f7ca464039b4f21705a8a7074f6c542c3e4937b4 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Fri, 22 Mar 2013 05:50:45 -0400 Subject: [PATCH] [1.5.x] Added missing markup to docs. Backport of 93cffc3b37 from master. --- docs/howto/custom-model-fields.txt | 6 +- docs/internals/deprecation.txt | 2 +- docs/intro/tutorial03.txt | 4 +- .../class-based-views/mixins-date-based.txt | 16 +++--- .../mixins-single-object.txt | 2 +- docs/ref/clickjacking.txt | 27 ++++----- docs/ref/contrib/admin/actions.txt | 2 +- docs/ref/contrib/csrf.txt | 2 +- docs/ref/contrib/gis/gdal.txt | 4 +- docs/ref/contrib/sitemaps.txt | 4 +- docs/ref/django-admin.txt | 2 +- docs/ref/models/fields.txt | 4 +- docs/ref/settings.txt | 2 +- docs/ref/template-response.txt | 2 +- docs/ref/urls.txt | 6 +- docs/releases/1.2-alpha-1.txt | 2 +- docs/releases/1.2.txt | 8 +-- docs/releases/1.3-alpha-1.txt | 2 +- docs/releases/1.3-beta-1.txt | 6 +- docs/releases/1.3.txt | 2 +- docs/releases/1.4-alpha-1.txt | 2 +- docs/releases/1.4-beta-1.txt | 2 +- docs/releases/1.4.txt | 2 +- docs/releases/1.5-alpha-1.txt | 15 +++-- docs/releases/1.5-beta-1.txt | 15 +++-- docs/releases/1.5.txt | 21 ++++--- docs/topics/auth/customizing.txt | 56 ++++++++++--------- docs/topics/auth/passwords.txt | 6 +- docs/topics/class-based-views/mixins.txt | 2 +- docs/topics/db/aggregation.txt | 36 ++++++------ docs/topics/db/managers.txt | 5 +- docs/topics/db/optimization.txt | 2 +- docs/topics/db/queries.txt | 4 +- docs/topics/http/shortcuts.txt | 5 +- docs/topics/logging.txt | 12 ++-- docs/topics/serialization.txt | 12 ++-- docs/topics/testing/overview.txt | 10 ++-- 37 files changed, 164 insertions(+), 148 deletions(-) diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 90771b7d0c..b5d79440be 100644 --- a/docs/howto/custom-model-fields.txt +++ b/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 `. 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 diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 55ab58d843..dd2548b956 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -111,7 +111,7 @@ See the :doc:`Django 1.3 release notes` 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`.) * The ``mod_python`` request handler will be removed. The ``mod_wsgi`` diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index daab8b7756..86cc5f97e6 100644 --- a/docs/intro/tutorial03.txt +++ b/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 diff --git a/docs/ref/class-based-views/mixins-date-based.txt b/docs/ref/class-based-views/mixins-date-based.txt index 7ff201e5a2..75f2a77615 100644 --- a/docs/ref/class-based-views/mixins-date-based.txt +++ b/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. diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt index 37468715f1..1b75acf267 100644 --- a/docs/ref/class-based-views/mixins-single-object.txt +++ b/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) diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index d78f8d34ac..96481906da 100644 --- a/docs/ref/clickjacking.txt +++ b/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 diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index 0a302ecd1d..c79f978850 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/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. diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index 32d8a705bc..8fb88f76ac 100644 --- a/docs/ref/contrib/csrf.txt +++ b/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 `_ 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 diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index 161efa39de..c68030673b 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/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) diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 3e8985b755..7c46874bfc 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/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 diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index a1f5cd5f85..d471b59eef 100644 --- a/docs/ref/django-admin.txt +++ b/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 diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 0cd0169681..793a1e1555 100644 --- a/docs/ref/models/fields.txt +++ b/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`` ----------------------------- diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 8624b9e9eb..9ed775981e 100644 --- a/docs/ref/settings.txt +++ b/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 ` for diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index 844b5fa46b..5c13ec7d96 100644 --- a/docs/ref/template-response.txt +++ b/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.) diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index 77dcc24311..d384b0e49b 100644 --- a/docs/ref/urls.txt +++ b/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 `. .. 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. :: diff --git a/docs/releases/1.2-alpha-1.txt b/docs/releases/1.2-alpha-1.txt index 16e1940e8f..8c905f6ef0 100644 --- a/docs/releases/1.2-alpha-1.txt +++ b/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 ` 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. diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt index 50c049f5da..ad39062ed1 100644 --- a/docs/releases/1.2.txt +++ b/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 ` 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 diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index ba8a4fc557..ed204f6297 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/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 diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt index 14897ed3b7..69f8023eb3 100644 --- a/docs/releases/1.3-beta-1.txt +++ b/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 diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 4c8dd2f81f..201d0cc1e4 100644 --- a/docs/releases/1.3.txt +++ b/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 diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt index 52d9b29baa..df7d03e834 100644 --- a/docs/releases/1.4-alpha-1.txt +++ b/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 diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt index b2e280c92d..23ef970592 100644 --- a/docs/releases/1.4-beta-1.txt +++ b/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 diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index bd7c647874..d69f95c9c3 100644 --- a/docs/releases/1.4.txt +++ b/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 diff --git a/docs/releases/1.5-alpha-1.txt b/docs/releases/1.5-alpha-1.txt index bb3f32a3be..2588b85306 100644 --- a/docs/releases/1.5-alpha-1.txt +++ b/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 ` supported bitwise operators by diff --git a/docs/releases/1.5-beta-1.txt b/docs/releases/1.5-beta-1.txt index 4dbe77f806..57b13ea6ce 100644 --- a/docs/releases/1.5-beta-1.txt +++ b/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 ` supported bitwise operators by diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index 9c5801102f..7b324db03f 100644 --- a/docs/releases/1.5.txt +++ b/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() ` 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 ` supported bitwise operators by diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index f15ce847cd..22d68f262d 100644 --- a/docs/topics/auth/customizing.txt +++ b/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 diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index 45fde9bbab..714b272219 100644 --- a/docs/topics/auth/passwords.txt +++ b/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 -------------------------- diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt index 2adbd406c7..9550d2fb86 100644 --- a/docs/topics/class-based-views/mixins.txt +++ b/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. diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 49134e24c0..125cd0bdee 100644 --- a/docs/topics/db/aggregation.txt +++ b/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 diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index a14616a17c..36b2ad0a94 100644 --- a/docs/topics/db/managers.txt +++ b/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. - diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index b5cca52e23..c1459ae247 100644 --- a/docs/topics/db/optimization.txt +++ b/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. diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 55129c2ef0..a6c369806e 100644 --- a/docs/topics/db/queries.txt +++ b/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) diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 68860f123f..961f0b9d96 100644 --- a/docs/topics/http/shortcuts.txt +++ b/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 + ` will be used to reverse-resolve the + name. * A URL, which will be used as-is for the redirect location. diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt index e2ce82f103..76c40d47c0 100644 --- a/docs/topics/logging.txt +++ b/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 diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index 2af0584a61..f53a620113 100644 --- a/docs/topics/serialization.txt +++ b/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 diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 7528ae141f..50c75ef729 100644 --- a/docs/topics/testing/overview.txt +++ b/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 `` HTML tag + Do this, for example, by making Selenium wait until the ```` 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 `` in the response might not necessarily be appropriate for all + of ```` in the response might not necessarily be appropriate for all use cases. Please refer to the `Selenium FAQ`_ and `Selenium documentation`_ for more information.