mirror of https://github.com/django/django.git
Fixed some typos and formatting issues in docs.
This commit is contained in:
parent
0d91225892
commit
2b6436e2d5
|
@ -17,8 +17,8 @@
|
||||||
{%- endmacro %}
|
{%- endmacro %}
|
||||||
|
|
||||||
{% block extrahead %}
|
{% block extrahead %}
|
||||||
{# When building htmlhelp (CHM format) disable JQuery inclusion, #}
|
{# When building htmlhelp (CHM format) disable jQuery inclusion, #}
|
||||||
{# as it causes problems in compiled CHM files. #}
|
{# as it causes problems in compiled CHM files. #}
|
||||||
{% if builder != "htmlhelp" %}
|
{% if builder != "htmlhelp" %}
|
||||||
{{ super() }}
|
{{ super() }}
|
||||||
<script type="text/javascript" src="{{ pathto('templatebuiltins.js', 1) }}"></script>
|
<script type="text/javascript" src="{{ pathto('templatebuiltins.js', 1) }}"></script>
|
||||||
|
|
|
@ -463,7 +463,7 @@ Jeremy Dunck
|
||||||
.. _Preston Holmes: http://www.ptone.com/
|
.. _Preston Holmes: http://www.ptone.com/
|
||||||
|
|
||||||
`Simon Charette`_
|
`Simon Charette`_
|
||||||
Simon is a mathematic student who discovered Django while searching for a
|
Simon is a mathematics student who discovered Django while searching for a
|
||||||
replacement framework to an in-house PHP entity. Since that faithful day
|
replacement framework to an in-house PHP entity. Since that faithful day
|
||||||
Django has been a big part of his life. So far, he's been involved in some
|
Django has been a big part of his life. So far, he's been involved in some
|
||||||
ORM and forms API fixes.
|
ORM and forms API fixes.
|
||||||
|
|
|
@ -112,7 +112,7 @@ or ought to be closed for any of the various reasons.
|
||||||
Accepted
|
Accepted
|
||||||
~~~~~~~~
|
~~~~~~~~
|
||||||
|
|
||||||
The big grey area! The absolute meaning of "accepted" is that the issue
|
The big gray area! The absolute meaning of "accepted" is that the issue
|
||||||
described in the ticket is valid and is in some stage of being worked on.
|
described in the ticket is valid and is in some stage of being worked on.
|
||||||
Beyond that there are several considerations:
|
Beyond that there are several considerations:
|
||||||
|
|
||||||
|
|
|
@ -7,7 +7,7 @@ be driving a release, you should follow these instructions to get the
|
||||||
package out.
|
package out.
|
||||||
|
|
||||||
**Please, keep these instructions up-to-date if you make changes!** The point
|
**Please, keep these instructions up-to-date if you make changes!** The point
|
||||||
here is to be descriptive, not proscriptive, so feel free to streamline or
|
here is to be descriptive, not prescriptive, so feel free to streamline or
|
||||||
otherwise make changes, but **update this document accordingly!**
|
otherwise make changes, but **update this document accordingly!**
|
||||||
|
|
||||||
Overview
|
Overview
|
||||||
|
|
|
@ -165,7 +165,7 @@ For example::
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
There's a `known bug`_ in Safari/Webkit which causes the named anchor to be
|
There's a `known bug`_ in Safari/WebKit which causes the named anchor to be
|
||||||
forgotten following a redirect. The practical impact for comments is that
|
forgotten following a redirect. The practical impact for comments is that
|
||||||
the Safari/webkit browsers will arrive at the correct page but will not
|
the Safari/webkit browsers will arrive at the correct page but will not
|
||||||
scroll to the named anchor.
|
scroll to the named anchor.
|
||||||
|
|
|
@ -132,7 +132,7 @@ Troubleshooting
|
||||||
If you can't find the solution to your problem here then participate in the
|
If you can't find the solution to your problem here then participate in the
|
||||||
community! You can:
|
community! You can:
|
||||||
|
|
||||||
* Join the ``#geodjango`` IRC channel on FreeNode. Please be patient and polite
|
* Join the ``#geodjango`` IRC channel on Freenode. Please be patient and polite
|
||||||
-- while you may not get an immediate response, someone will attempt to answer
|
-- while you may not get an immediate response, someone will attempt to answer
|
||||||
your question as soon as they see it.
|
your question as soon as they see it.
|
||||||
* Ask your question on the `GeoDjango`__ mailing list.
|
* Ask your question on the `GeoDjango`__ mailing list.
|
||||||
|
|
|
@ -125,8 +125,8 @@ untar::
|
||||||
$ tar xzf pysqlite-2.6.3.tar.gz
|
$ tar xzf pysqlite-2.6.3.tar.gz
|
||||||
$ cd pysqlite-2.6.3
|
$ cd pysqlite-2.6.3
|
||||||
|
|
||||||
Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
|
Next, use a text editor to edit the ``setup.cfg`` file to look like the
|
||||||
to look like the following:
|
following:
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
|
|
|
@ -603,7 +603,7 @@ Version 3.6.2
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
SQLite version 3.6.2 (released August 30, 2008) introduced a bug into ``SELECT
|
SQLite version 3.6.2 (released August 30, 2008) introduced a bug into ``SELECT
|
||||||
DISTINCT`` handling that is triggered by, amongst other things, Django's
|
DISTINCT`` handling that is triggered by, among other things, Django's
|
||||||
``DateQuerySet`` (returned by the ``dates()`` method on a queryset).
|
``DateQuerySet`` (returned by the ``dates()`` method on a queryset).
|
||||||
|
|
||||||
You should avoid using this version of SQLite with Django. Either upgrade to
|
You should avoid using this version of SQLite with Django. Either upgrade to
|
||||||
|
|
|
@ -84,7 +84,7 @@ GZip middleware
|
||||||
Security researchers recently revealed that when compression techniques
|
Security researchers recently revealed that when compression techniques
|
||||||
(including ``GZipMiddleware``) are used on a website, the site becomes
|
(including ``GZipMiddleware``) are used on a website, the site becomes
|
||||||
exposed to a number of possible attacks. These approaches can be used to
|
exposed to a number of possible attacks. These approaches can be used to
|
||||||
compromise, amongst other things, Django's CSRF protection. Before using
|
compromise, among other things, Django's CSRF protection. Before using
|
||||||
``GZipMiddleware`` on your site, you should consider very carefully whether
|
``GZipMiddleware`` on your site, you should consider very carefully whether
|
||||||
you are subject to these attacks. If you're in *any* doubt about whether
|
you are subject to these attacks. If you're in *any* doubt about whether
|
||||||
you're affected, you should avoid using ``GZipMiddleware``. For more
|
you're affected, you should avoid using ``GZipMiddleware``. For more
|
||||||
|
|
|
@ -641,7 +641,7 @@ will be displayed if the value has not changed::
|
||||||
{% ifchanged match.ballot_id %}
|
{% ifchanged match.ballot_id %}
|
||||||
{% cycle "red" "blue" %}
|
{% cycle "red" "blue" %}
|
||||||
{% else %}
|
{% else %}
|
||||||
grey
|
gray
|
||||||
{% endifchanged %}
|
{% endifchanged %}
|
||||||
">{{ match }}</div>
|
">{{ match }}</div>
|
||||||
{% endfor %}
|
{% endfor %}
|
||||||
|
|
|
@ -29,8 +29,8 @@ into account when building its cache key. Requests with the same path but
|
||||||
different header content for headers named in ``Vary`` need to get different
|
different header content for headers named in ``Vary`` need to get different
|
||||||
cache keys to prevent delivery of wrong content.
|
cache keys to prevent delivery of wrong content.
|
||||||
|
|
||||||
For example, :doc:`internationalization </topics/i18n/index>` middleware would need
|
For example, :doc:`internationalization </topics/i18n/index>` middleware would
|
||||||
to distinguish caches by the ``Accept-language`` header.
|
need to distinguish caches by the ``Accept-language`` header.
|
||||||
|
|
||||||
.. function:: patch_cache_control(response, **kwargs)
|
.. function:: patch_cache_control(response, **kwargs)
|
||||||
|
|
||||||
|
@ -289,7 +289,8 @@ The functions defined in this module share the following properties:
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
.. module:: django.utils.feedgenerator
|
.. module:: django.utils.feedgenerator
|
||||||
:synopsis: Syndication feed generation library -- used for generating RSS, etc.
|
:synopsis: Syndication feed generation library -- used for generating RSS,
|
||||||
|
etc.
|
||||||
|
|
||||||
Sample usage::
|
Sample usage::
|
||||||
|
|
||||||
|
@ -485,15 +486,16 @@ Atom1Feed
|
||||||
|
|
||||||
.. function:: allow_lazy(func, *resultclasses)
|
.. function:: allow_lazy(func, *resultclasses)
|
||||||
|
|
||||||
Django offers many utility functions (particularly in ``django.utils``) that
|
Django offers many utility functions (particularly in ``django.utils``)
|
||||||
take a string as their first argument and do something to that string. These
|
that take a string as their first argument and do something to that string.
|
||||||
functions are used by template filters as well as directly in other code.
|
These functions are used by template filters as well as directly in other
|
||||||
|
code.
|
||||||
|
|
||||||
If you write your own similar functions and deal with translations, you'll
|
If you write your own similar functions and deal with translations, you'll
|
||||||
face the problem of what to do when the first argument is a lazy translation
|
face the problem of what to do when the first argument is a lazy
|
||||||
object. You don't want to convert it to a string immediately, because you might
|
translation object. You don't want to convert it to a string immediately,
|
||||||
be using this function outside of a view (and hence the current thread's locale
|
because you might be using this function outside of a view (and hence the
|
||||||
setting will not be correct).
|
current thread's locale setting will not be correct).
|
||||||
|
|
||||||
For cases like this, use the ``django.utils.functional.allow_lazy()``
|
For cases like this, use the ``django.utils.functional.allow_lazy()``
|
||||||
decorator. It modifies the function so that *if* it's called with a lazy
|
decorator. It modifies the function so that *if* it's called with a lazy
|
||||||
|
@ -510,15 +512,15 @@ Atom1Feed
|
||||||
# Replace unicode by str on Python 3
|
# Replace unicode by str on Python 3
|
||||||
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
|
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
|
||||||
|
|
||||||
The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
|
The ``allow_lazy()`` decorator takes, in addition to the function to
|
||||||
a number of extra arguments (``*args``) specifying the type(s) that the
|
decorate, a number of extra arguments (``*args``) specifying the type(s)
|
||||||
original function can return. Usually, it's enough to include ``unicode``
|
that the original function can return. Usually, it's enough to include
|
||||||
(or ``str`` on Python 3) here and ensure that your function returns only
|
``unicode`` (or ``str`` on Python 3) here and ensure that your function
|
||||||
Unicode strings.
|
returns only Unicode strings.
|
||||||
|
|
||||||
Using this decorator means you can write your function and assume that the
|
Using this decorator means you can write your function and assume that the
|
||||||
input is a proper string, then add support for lazy translation objects at the
|
input is a proper string, then add support for lazy translation objects at
|
||||||
end.
|
the end.
|
||||||
|
|
||||||
``django.utils.html``
|
``django.utils.html``
|
||||||
=====================
|
=====================
|
||||||
|
@ -540,8 +542,8 @@ escaping HTML.
|
||||||
|
|
||||||
.. function:: conditional_escape(text)
|
.. function:: conditional_escape(text)
|
||||||
|
|
||||||
Similar to ``escape()``, except that it doesn't operate on pre-escaped strings,
|
Similar to ``escape()``, except that it doesn't operate on pre-escaped
|
||||||
so it will not double escape.
|
strings, so it will not double escape.
|
||||||
|
|
||||||
.. function:: format_html(format_string, *args, **kwargs)
|
.. function:: format_html(format_string, *args, **kwargs)
|
||||||
|
|
||||||
|
@ -601,9 +603,9 @@ escaping HTML.
|
||||||
|
|
||||||
strip_tags(value)
|
strip_tags(value)
|
||||||
|
|
||||||
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
|
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``
|
||||||
return value will be ``"Joel is a slug"``. Note that ``strip_tags`` result
|
the return value will be ``"Joel is a slug"``. Note that ``strip_tags``
|
||||||
may still contain unsafe HTML content, so you might use
|
result may still contain unsafe HTML content, so you might use
|
||||||
:func:`~django.utils.html.escape` to make it a safe string.
|
:func:`~django.utils.html.escape` to make it a safe string.
|
||||||
|
|
||||||
.. versionchanged:: 1.6
|
.. versionchanged:: 1.6
|
||||||
|
@ -618,13 +620,13 @@ escaping HTML.
|
||||||
|
|
||||||
remove_tags(value, "b span")
|
remove_tags(value, "b span")
|
||||||
|
|
||||||
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
|
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``
|
||||||
return value will be ``"Joel <button>is</button> a slug"``.
|
the return value will be ``"Joel <button>is</button> a slug"``.
|
||||||
|
|
||||||
Note that this filter is case-sensitive.
|
Note that this filter is case-sensitive.
|
||||||
|
|
||||||
If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the
|
If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"``
|
||||||
return value will be ``"<B>Joel</B> <button>is</button> a slug"``.
|
the return value will be ``"<B>Joel</B> <button>is</button> a slug"``.
|
||||||
|
|
||||||
.. _str.format: http://docs.python.org/library/stdtypes.html#str.format
|
.. _str.format: http://docs.python.org/library/stdtypes.html#str.format
|
||||||
|
|
||||||
|
@ -738,7 +740,8 @@ Functions for working with Python modules.
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
.. module:: django.utils.safestring
|
.. module:: django.utils.safestring
|
||||||
:synopsis: Functions and classes for working with strings that can be displayed safely without further escaping in HTML.
|
:synopsis: Functions and classes for working with strings that can be
|
||||||
|
displayed safely without further escaping in HTML.
|
||||||
|
|
||||||
Functions and classes for working with "safe strings": strings that can be
|
Functions and classes for working with "safe strings": strings that can be
|
||||||
displayed safely without further escaping in HTML. Marking something as a "safe
|
displayed safely without further escaping in HTML. Marking something as a "safe
|
||||||
|
@ -801,14 +804,15 @@ appropriate entities.
|
||||||
.. function:: slugify
|
.. function:: slugify
|
||||||
|
|
||||||
Converts to lowercase, removes non-word characters (alphanumerics and
|
Converts to lowercase, removes non-word characters (alphanumerics and
|
||||||
underscores) and converts spaces to hyphens. Also strips leading and trailing
|
underscores) and converts spaces to hyphens. Also strips leading and
|
||||||
whitespace.
|
trailing whitespace.
|
||||||
|
|
||||||
For example::
|
For example::
|
||||||
|
|
||||||
slugify(value)
|
slugify(value)
|
||||||
|
|
||||||
If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
|
If ``value`` is ``"Joel is a slug"``, the output will be
|
||||||
|
``"joel-is-a-slug"``.
|
||||||
|
|
||||||
``django.utils.translation``
|
``django.utils.translation``
|
||||||
============================
|
============================
|
||||||
|
@ -880,30 +884,30 @@ For a complete discussion on the usage of the following see the
|
||||||
|
|
||||||
.. function:: activate(language)
|
.. function:: activate(language)
|
||||||
|
|
||||||
Fetches the translation object for a given language and installs it as
|
Fetches the translation object for a given language and activates it as
|
||||||
the current translation object for the current thread.
|
the current translation object for the current thread.
|
||||||
|
|
||||||
.. function:: deactivate()
|
.. function:: deactivate()
|
||||||
|
|
||||||
De-installs the currently active translation object so that further _ calls
|
Deactivates the currently active translation object so that further _ calls
|
||||||
will resolve against the default translation object, again.
|
will resolve against the default translation object, again.
|
||||||
|
|
||||||
.. function:: deactivate_all()
|
.. function:: deactivate_all()
|
||||||
|
|
||||||
Makes the active translation object a NullTranslations() instance. This is
|
Makes the active translation object a ``NullTranslations()`` instance.
|
||||||
useful when we want delayed translations to appear as the original string
|
This is useful when we want delayed translations to appear as the original
|
||||||
for some reason.
|
string for some reason.
|
||||||
|
|
||||||
.. function:: override(language, deactivate=False)
|
.. function:: override(language, deactivate=False)
|
||||||
|
|
||||||
A Python context manager that uses
|
A Python context manager that uses
|
||||||
:func:`django.utils.translation.activate` to fetch the translation object
|
:func:`django.utils.translation.activate` to fetch the translation object
|
||||||
for a given language, installing it as the translation object for the
|
for a given language, activates it as the translation object for the
|
||||||
current thread and reinstall the previous active language on exit.
|
current thread and reactivates the previous active language on exit.
|
||||||
Optionally it can simply uninstall the temporary translation on exit with
|
Optionally, it can simply deactivate the temporary translation on exit with
|
||||||
:func:`django.utils.translation.deactivate` if the deactivate argument is
|
:func:`django.utils.translation.deactivate` if the ``deactivate`` argument
|
||||||
True. If you pass None as the language argument, a NullTranslations()
|
is ``True``. If you pass ``None`` as the language argument, a
|
||||||
instance is installed while the context is active.
|
``NullTranslations()`` instance is activated within the context.
|
||||||
|
|
||||||
.. function:: get_language()
|
.. function:: get_language()
|
||||||
|
|
||||||
|
@ -918,10 +922,10 @@ For a complete discussion on the usage of the following see the
|
||||||
|
|
||||||
.. function:: get_language_from_request(request, check_path=False)
|
.. function:: get_language_from_request(request, check_path=False)
|
||||||
|
|
||||||
Analyzes the request to find what language the user wants the system to show.
|
Analyzes the request to find what language the user wants the system to
|
||||||
Only languages listed in settings.LANGUAGES are taken into account. If the user
|
show. Only languages listed in settings.LANGUAGES are taken into account.
|
||||||
requests a sublanguage where we have a main language, we send out the main
|
If the user requests a sublanguage where we have a main language, we send
|
||||||
language.
|
out the main language.
|
||||||
|
|
||||||
If ``check_path`` is ``True``, the function first checks the requested URL
|
If ``check_path`` is ``True``, the function first checks the requested URL
|
||||||
for whether its path begins with a language code listed in the
|
for whether its path begins with a language code listed in the
|
||||||
|
@ -933,13 +937,14 @@ For a complete discussion on the usage of the following see the
|
||||||
|
|
||||||
.. function:: templatize(src)
|
.. function:: templatize(src)
|
||||||
|
|
||||||
Turns a Django template into something that is understood by xgettext. It does
|
Turns a Django template into something that is understood by ``xgettext``.
|
||||||
so by translating the Django translation tags into standard gettext function
|
It does so by translating the Django translation tags into standard
|
||||||
invocations.
|
``gettext`` function invocations.
|
||||||
|
|
||||||
.. data:: LANGUAGE_SESSION_KEY
|
.. data:: LANGUAGE_SESSION_KEY
|
||||||
|
|
||||||
Session key under which the active language for the current session is stored.
|
Session key under which the active language for the current session is
|
||||||
|
stored.
|
||||||
|
|
||||||
.. _time-zone-selection-functions:
|
.. _time-zone-selection-functions:
|
||||||
|
|
||||||
|
@ -1062,7 +1067,8 @@ For a complete discussion on the usage of the following see the
|
||||||
Use :mod:`~django.utils.timezone` instead.
|
Use :mod:`~django.utils.timezone` instead.
|
||||||
|
|
||||||
.. module:: django.utils.tzinfo
|
.. module:: django.utils.tzinfo
|
||||||
:synopsis: Implementation of ``tzinfo`` classes for use with ``datetime.datetime``.
|
:synopsis: Implementation of ``tzinfo`` classes for use with
|
||||||
|
``datetime.datetime``.
|
||||||
|
|
||||||
.. class:: FixedOffset
|
.. class:: FixedOffset
|
||||||
|
|
||||||
|
|
|
@ -219,7 +219,7 @@ processing to work on a particular object, identified from the URL,
|
||||||
we'll want the functionality provided by
|
we'll want the functionality provided by
|
||||||
:class:`~django.views.generic.detail.SingleObjectMixin`.
|
:class:`~django.views.generic.detail.SingleObjectMixin`.
|
||||||
|
|
||||||
We'll demonstrate this with the publisher modeling we used in the
|
We'll demonstrate this with the ``Author`` model we used in the
|
||||||
:doc:`generic class-based views introduction<generic-display>`.
|
:doc:`generic class-based views introduction<generic-display>`.
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
|
@ -29,7 +29,7 @@ Essentially, Django does two things:
|
||||||
their preferences.
|
their preferences.
|
||||||
|
|
||||||
Obviously, translation depends on the target language, and formatting usually
|
Obviously, translation depends on the target language, and formatting usually
|
||||||
depends on the target country. These informations are provided by browsers in
|
depends on the target country. This information is provided by browsers in
|
||||||
the ``Accept-Language`` header. However, the time zone isn't readily available.
|
the ``Accept-Language`` header. However, the time zone isn't readily available.
|
||||||
|
|
||||||
Definitions
|
Definitions
|
||||||
|
|
Loading…
Reference in New Issue