From 93cffc3b37d7ef7a20c53f9001f0451a37be7584 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Fri, 22 Mar 2013 05:50:45 -0400 Subject: [PATCH] Added missing markup to docs. --- 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 | 28 +++++----- 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 | 24 ++++---- docs/topics/testing/overview.txt | 10 ++-- 37 files changed, 170 insertions(+), 155 deletions(-) diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 84b3881fad..8993872cff 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 c0863278b5..bf1a323489 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 299ac56ac6..bbe930d79e 100644 --- a/docs/ref/class-based-views/mixins-single-object.txt +++ b/docs/ref/class-based-views/mixins-single-object.txt @@ -59,7 +59,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 40b42d1ac7..ce27148ad3 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -30,10 +30,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 @@ -51,7 +51,7 @@ How to use it Setting X-Frame-Options for all responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To set the same X-Frame-Options value for all responses in your site, put +To set the same ``X-Frame-Options`` value for all responses in your site, put ``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to :setting:`MIDDLEWARE_CLASSES`:: @@ -65,15 +65,15 @@ To set the same X-Frame-Options value for all responses in your site, put This middleware is enabled in the settings file generated by :djadmin:`startproject`. -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 @@ -86,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 @@ -107,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 @@ -123,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 14522d8dbc..968ef0b07b 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 ded7a84fbc..d37ee83378 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -454,8 +454,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 ac257db9f5..6277b22a30 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -1385,7 +1385,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 39b84170fe..421de74c62 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -872,8 +872,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 2d24ccb441..92500d19d1 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2174,7 +2174,7 @@ Settings for :mod:`django.contrib.messages`. MESSAGE_LEVEL ------------- -Default: `messages.INFO` +Default: ``messages.INFO`` Sets the minimum message level that will be recorded by the messages framework. See :ref:`message levels ` for more details. 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 92b41b8fea..59fb97828c 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -23,12 +23,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 53d38a006b..7c9f233921 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/docs/releases/1.3-alpha-1.txt @@ -277,7 +277,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 582bceffca..f689a3dffd 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -662,7 +662,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 09855400eb..92ec0b6483 100644 --- a/docs/releases/1.4-alpha-1.txt +++ b/docs/releases/1.4-alpha-1.txt @@ -878,7 +878,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 8ea63742e3..d3f1bb807d 100644 --- a/docs/releases/1.4-beta-1.txt +++ b/docs/releases/1.4-beta-1.txt @@ -946,7 +946,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 9459e940b4..3025a37098 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -1040,7 +1040,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 75d2ed0b46..d6ded36a94 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -144,9 +144,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. @@ -222,7 +222,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. @@ -292,8 +294,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 @@ -310,8 +312,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 @@ -663,7 +666,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 85124181c6..50ad99c61d 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -103,12 +103,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 @@ -183,9 +185,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 @@ -482,7 +482,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 @@ -497,7 +497,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): @@ -605,11 +605,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: @@ -617,26 +617,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: @@ -705,7 +707,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` @@ -721,8 +723,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 @@ -732,21 +734,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 @@ -911,7 +913,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 3d95b4b387..d9b7e24efc 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -102,9 +102,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 a8c0d17076..dc2f90c8a2 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -191,7 +191,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_ @@ -369,7 +369,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. @@ -413,4 +413,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 91cd4fa871..f19302974d 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 3b68914c1a..cb22a57e84 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 @@ -544,7 +544,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': { @@ -564,7 +564,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: @@ -576,8 +576,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 to 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 82cb3ffe5b..ce39f6cd28 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) @@ -176,7 +176,7 @@ XML ~~~ The basic XML serialization format is quite simple:: - + @@ -196,7 +196,7 @@ fields "type" and "name". The text content of the element represents the value that should be stored. Foreign keys and other relational fields are treated a little bit differently:: - + 9 @@ -208,7 +208,7 @@ a foreign key to the contenttypes.ContentType instance with the PK 9. ManyToMany-relations are exported for the model that binds them. For instance, the auth.User model has such a relation to the auth.Permission model:: - + @@ -224,7 +224,7 @@ JSON When staying with the same example data as before it would be serialized as JSON in the following way:: - + [ { "pk": "4b678b301dfd8a4e0dad910de3ae245b", @@ -242,7 +242,7 @@ with three properties: "pk", "model" and "fields". "fields" is again an object containing each field's name and value as property and property-value respectively. -Foreign keys just have the PK of the linked object as property value. +Foreign keys just have the PK of the linked object as property value. ManyToMany-relations are serialized for the model that defines them and are represented as a list of PKs. @@ -273,7 +273,7 @@ YAML YAML serialization looks quite similar to JSON. The object list is serialized as a sequence mappings with the keys "pk", "model" and "fields". Each field is again a mapping with the key being name of the field and the value the value:: - + - fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'} model: sessions.session pk: 4b678b301dfd8a4e0dad910de3ae245b @@ -439,7 +439,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:: @@ -458,7 +458,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 cb1c8dc52a..628a161554 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -975,8 +975,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: @@ -1010,7 +1010,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 @@ -1117,7 +1117,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 @@ -1134,7 +1134,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.