mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 06:06:09 +00:00
Code Issues 32 Releases Wiki Activity

Refs #36485 -- Rewrapped docs to 79 columns line length.

Browse Source 
Lines in the docs files were manually adjusted to conform to the
79 columns limit per line (plus newline), improving readability and
consistency across the content.
This commit is contained in:
David Smith
2025-07-25 10:24:17 +01:00
committed by nessita
parent 4286a23df6
commit f81e6e3a53
230 changed files with 3250 additions and 2914 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/ref/templates/api.txt
View File

@@ -115,9 +115,10 @@ overridden by what's passed by
It defaults to ``'utf-8'``.
* ``'libraries'``: A dictionary of labels and dotted Python paths of template
tag modules to register with the template engine. This is used to add new
libraries or provide alternate labels for existing ones. For example::
* ``'libraries'``: A dictionary of labels and dotted Python paths of
template tag modules to register with the template engine. This is used
to add new libraries or provide alternate labels for existing ones. For
example::
Engine(
libraries={
@@ -136,8 +137,8 @@ overridden by what's passed by
builtins=["myapp.builtins"],
)
Tags and filters from built-in libraries can be used without first calling
the :ttag:`{% load %}<load>` tag.
Tags and filters from built-in libraries can be used without first
calling the :ttag:`{% load %}<load>` tag.
.. staticmethod:: Engine.get_default()
@@ -434,11 +435,11 @@ Django's template language has no way to escape the characters used for its own
syntax. For example, the :ttag:`templatetag` tag is required if you need to
output character sequences like ``{%`` and ``%}``.
A similar issue exists if you want to include these sequences in template filter
or tag arguments. For example, when parsing a block tag, Django's template
parser looks for the first occurrence of ``%}`` after a ``{%``. This prevents
the use of ``"%}"`` as a string literal. For example, a ``TemplateSyntaxError``
will be raised for the following expressions:
A similar issue exists if you want to include these sequences in template
filter or tag arguments. For example, when parsing a block tag, Django's
template parser looks for the first occurrence of ``%}`` after a ``{%``. This
prevents the use of ``"%}"`` as a string literal. For example, a
``TemplateSyntaxError`` will be raised for the following expressions:
.. code-block:: html+django
@@ -588,8 +589,8 @@ tags <howto-writing-custom-template-tags>`.
.. method:: Context.flatten()
Using ``flatten()`` method you can get whole ``Context`` stack as one dictionary
including builtin variables.
Using ``flatten()`` method you can get whole ``Context`` stack as one
dictionary including builtin variables.
.. code-block:: pycon
@@ -600,7 +601,8 @@ including builtin variables.
>>> c.flatten()
{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}
A ``flatten()`` method is also internally used to make ``Context`` objects comparable.
A ``flatten()`` method is also internally used to make ``Context`` objects
comparable.
.. code-block:: pycon

62
docs/ref/templates/builtins.txt
View File

@@ -1251,11 +1251,11 @@ you can also write the previous example as:
{% endfor %}
</ul>
Note that ``{% regroup %}`` does not order its input! Our example relies on
the fact that the ``cities`` list was ordered by ``country`` in the first place.
If the ``cities`` list did *not* order its members by ``country``, the
regrouping would naively display more than one group for a single country. For
example, say the ``cities`` list was set to this (note that the countries are not
Note that ``{% regroup %}`` does not order its input! Our example relies on the
fact that the ``cities`` list was ordered by ``country`` in the first place. If
the ``cities`` list did *not* order its members by ``country``, the regrouping
would naively display more than one group for a single country. For example,
say the ``cities`` list was set to this (note that the countries are not
grouped together):
.. code-block:: python
@@ -1588,7 +1588,8 @@ image in the above example will be 88 pixels wide
(because 175/200 = .875; .875 * 100 = 87.5 which is rounded up to 88).
In some cases you might want to capture the result of ``widthratio`` in a
variable. It can be useful, for instance, in a :ttag:`blocktranslate` like this:
variable. It can be useful, for instance, in a :ttag:`blocktranslate` like
this:
.. code-block:: html+django
@@ -1740,7 +1741,8 @@ differences.
.. note::
These format characters are not used in Django outside of templates. They
were designed to be compatible with PHP to ease transitioning for designers.
were designed to be compatible with PHP to ease transitioning for
designers.
.. _date-and-time-formatting-specifiers:
@@ -1754,32 +1756,32 @@ Format character Description Example output
leading zeros.
``j`` Day of the month without leading ``'1'`` to ``'31'``
zeros.
``D`` Day of the week, textual, 3 letters. ``'Fri'``
``l`` Day of the week, textual, long. ``'Friday'``
``D`` Day of the week, textual, 3 letters. ``'Fri'``
``l`` Day of the week, textual, long. ``'Friday'``
``S`` English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``
month, 2 characters.
``w`` Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday)
leading zeros.
``z`` Day of the year. ``1`` to ``366``
``z`` Day of the year. ``1`` to ``366``
**Week**
``W`` ISO-8601 week number of year, with ``1``, ``53``
weeks starting on Monday.
**Month**
``m`` Month, 2 digits with leading zeros. ``'01'`` to ``'12'``
``n`` Month without leading zeros. ``'1'`` to ``'12'``
``M`` Month, textual, 3 letters. ``'Jan'``
``b`` Month, textual, 3 letters, lowercase. ``'jan'``
``m`` Month, 2 digits with leading zeros. ``'01'`` to ``'12'``
``n`` Month without leading zeros. ``'1'`` to ``'12'``
``M`` Month, textual, 3 letters. ``'Jan'``
``b`` Month, textual, 3 letters, lowercase. ``'jan'``
``E`` Month, locale specific alternative
representation usually used for long
date representation. ``'listopada'`` (for Polish locale, as opposed to ``'Listopad'``)
``F`` Month, textual, long. ``'January'``
date representation. ``'listopada'`` (for Polish locale, as opposed to ``'Listopad'``)
``F`` Month, textual, long. ``'January'``
``N`` Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'``
style. Proprietary extension.
``t`` Number of days in the given month. ``28`` to ``31``
``t`` Number of days in the given month. ``28`` to ``31``
**Year**
``y`` Year, 2 digits with leading zeros. ``'00'`` to ``'99'``
``Y`` Year, 4 digits with leading zeros. ``'0001'``, ..., ``'1999'``, ..., ``'9999'``
``L`` Boolean for whether it's a leap year. ``True`` or ``False``
``y`` Year, 2 digits with leading zeros. ``'00'`` to ``'99'``
``Y`` Year, 4 digits with leading zeros. ``'0001'``, ..., ``'1999'``, ..., ``'9999'``
``L`` Boolean for whether it's a leap year. ``True`` or ``False``
``o`` ISO-8601 week-numbering year, ``'1999'``
corresponding to the ISO-8601 week
number (W) which uses leap weeks. See Y
@@ -1789,16 +1791,16 @@ Format character Description Example output
zeros.
``G`` Hour, 24-hour format without leading ``'0'`` to ``'23'``
zeros.
``h`` Hour, 12-hour format. ``'01'`` to ``'12'``
``H`` Hour, 24-hour format. ``'00'`` to ``'23'``
``i`` Minutes. ``'00'`` to ``'59'``
``s`` Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'``
``u`` Microseconds. ``000000`` to ``999999``
``h`` Hour, 12-hour format. ``'01'`` to ``'12'``
``H`` Hour, 24-hour format. ``'00'`` to ``'23'``
``i`` Minutes. ``'00'`` to ``'59'``
``s`` Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'``
``u`` Microseconds. ``000000`` to ``999999``
``a`` ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'``
this is slightly different than PHP's
output, because this includes periods
to match Associated Press style.)
``A`` ``'AM'`` or ``'PM'``. ``'AM'``
``A`` ``'AM'`` or ``'PM'``. ``'AM'``
``f`` Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'``
with minutes left off if they're zero.
Proprietary extension.
@@ -1813,8 +1815,8 @@ Format character Description Example output
depending on the datetime.
``I`` Daylight saving time, whether it's in ``'1'`` or ``'0'``
effect or not.
``O`` Difference to Greenwich time in hours. ``'+0200'``
``T`` Time zone of this machine. ``'EST'``, ``'MDT'``
``O`` Difference to Greenwich time in hours. ``'+0200'``
``T`` Time zone of this machine. ``'EST'``, ``'MDT'``
``Z`` Time zone offset in seconds. The ``-43200`` to ``43200``
offset for timezones west of UTC is
always negative, and for those east of
@@ -2519,8 +2521,8 @@ Example:
If ``num_messages`` is ``1``, the output will be ``You have 1 message.``
If ``num_messages`` is ``2`` the output will be ``You have 2 messages.``
For words that require a suffix other than ``'s'``, you can provide an alternate
suffix as a parameter to the filter.
For words that require a suffix other than ``'s'``, you can provide an
alternate suffix as a parameter to the filter.
Example:

59
docs/ref/templates/language.txt
View File

@@ -20,12 +20,13 @@ or Jinja2_, you should feel right at home with Django's templates.
presentation, not program logic.
The Django template system provides tags which function similarly to some
programming constructs -- an :ttag:`if` tag for boolean tests, a :ttag:`for`
tag for looping, etc. -- but these are not simply executed as the
corresponding Python code, and the template system will not execute
arbitrary Python expressions. Only the tags, filters and syntax listed below
are supported by default (although you can add :doc:`your own extensions
</howto/custom-template-tags>` to the template language as needed).
programming constructs -- an :ttag:`if` tag for boolean tests, a
:ttag:`for` tag for looping, etc. -- but these are not simply executed as
the corresponding Python code, and the template system will not execute
arbitrary Python expressions. Only the tags, filters and syntax listed
below are supported by default (although you can add :doc:`your own
extensions </howto/custom-template-tags>` to the template language as
needed).
.. _`The Django template language: For Python programmers`: ../templates_python/
.. _Smarty: https://www.smarty.net/
@@ -97,8 +98,8 @@ Use a dot (``.``) to access attributes of a variable.
result of the call becomes the template value.
This lookup order can cause some unexpected behavior with objects that
override dictionary lookup. For example, consider the following code snippet
that attempts to loop over a ``collections.defaultdict``:
override dictionary lookup. For example, consider the following code
snippet that attempts to loop over a ``collections.defaultdict``:
.. code-block:: html+django
@@ -106,9 +107,9 @@ Use a dot (``.``) to access attributes of a variable.
Do something with k and v here...
{% endfor %}
Because dictionary lookup happens first, that behavior kicks in and provides
a default value instead of using the intended ``.items()`` method. In this
case, consider converting to a dictionary first.
Because dictionary lookup happens first, that behavior kicks in and
provides a default value instead of using the intended ``.items()`` method.
In this case, consider converting to a dictionary first.
In the above example, ``{{ section.title }}`` will be replaced with the
``title`` attribute of the ``section`` object.
@@ -202,10 +203,10 @@ some load external information into the template to be used by later variables.
Some tags require beginning and ending tags (i.e. ``{% tag %} ... tag contents
... {% endtag %}``).
Django ships with about two dozen built-in template tags. You can read all about
them in the :ref:`built-in tag reference <ref-templates-builtins-tags>`. To give
you a taste of what's available, here are some of the more commonly used
tags:
Django ships with about two dozen built-in template tags. You can read all
about them in the :ref:`built-in tag reference <ref-templates-builtins-tags>`.
To give you a taste of what's available, here are some of the more commonly
used tags:
:ttag:`for`
Loop over each item in an array. For example, to display a list of athletes
@@ -288,9 +289,9 @@ A comment can contain any template code, invalid or not. For example:
{# {% if foo %}bar{% else %} #}
This syntax can only be used for single-line comments (no newlines are permitted
between the ``{#`` and ``#}`` delimiters). If you need to comment out a
multiline portion of the template, see the :ttag:`comment` tag.
This syntax can only be used for single-line comments (no newlines are
permitted between the ``{#`` and ``#}`` delimiters). If you need to comment out
a multiline portion of the template, see the :ttag:`comment` tag.
.. _template-inheritance:
@@ -389,8 +390,8 @@ like:
</html>
Note that since the child template didn't define the ``sidebar`` block, the
value from the parent template is used instead. Content within a ``{% block %}``
tag in a parent template is always used as a fallback.
value from the parent template is used instead. Content within a
``{% block %}`` tag in a parent template is always used as a fallback.
You can use as many levels of inheritance as needed. One common way of using
inheritance is the following three-level approach:
@@ -410,12 +411,12 @@ areas, such as section-wide navigation.
Here are some tips for working with inheritance:
* If you use :ttag:`{% extends %}<extends>` in a template, it must be the first template
tag in that template. Template inheritance won't work, otherwise.
* If you use :ttag:`{% extends %}<extends>` in a template, it must be the first
template tag in that template. Template inheritance won't work, otherwise.
* More :ttag:`{% block %}<block>` tags in your base templates are better. Remember,
child templates don't have to define all parent blocks, so you can fill
in reasonable defaults in a number of blocks, then only define the ones
* More :ttag:`{% block %}<block>` tags in your base templates are better.
Remember, child templates don't have to define all parent blocks, so you can
fill in reasonable defaults in a number of blocks, then only define the ones
you need later. It's better to have more hooks than fewer hooks.
* If you find yourself duplicating content in a number of templates, it
@@ -894,8 +895,8 @@ tag in a template:
{{ 45000|intcomma }}
In the above, the :ttag:`load` tag loads the ``humanize`` tag library, which then
makes the ``intcomma`` filter available for use. If you've enabled
In the above, the :ttag:`load` tag loads the ``humanize`` tag library, which
then makes the ``intcomma`` filter available for use. If you've enabled
:mod:`django.contrib.admindocs`, you can consult the documentation area in your
admin to find the list of custom libraries in your installation.
@@ -906,8 +907,8 @@ Example:
{% load humanize i18n %}
See :doc:`/howto/custom-template-tags` for information on writing your own custom
template libraries.
See :doc:`/howto/custom-template-tags` for information on writing your own
custom template libraries.
Custom libraries and template inheritance
-----------------------------------------