Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed many more ReST indentation errors, somehow accidentally missed …

…from [16955]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit d1e5c55258d624058a93c8cacdb1f25ae7857554 1 parent 5109ac3
Luke Plant spookylukey authored
Showing with 5,861 additions and 5,893 deletions.
  1. +10 −10 docs/faq/admin.txt
  2. +9 −9 docs/faq/contributing.txt
  3. +5 −5 docs/faq/install.txt
  4. +29 −29 docs/faq/usage.txt
  5. +22 −22 docs/howto/apache-auth.txt
  6. +5 −5 docs/howto/custom-file-storage.txt
  7. +60 −60 docs/howto/custom-model-fields.txt
  8. +202 −202 docs/howto/custom-template-tags.txt
  9. +3 −3 docs/howto/deployment/fastcgi.txt
  10. +17 −17 docs/howto/deployment/modpython.txt
  11. +9 −9 docs/howto/deployment/modwsgi.txt
  12. +36 −48 docs/howto/error-reporting.txt
  13. +16 −16 docs/howto/i18n.txt
  14. +6 −6 docs/howto/jython.txt
  15. +6 −6 docs/howto/legacy-databases.txt
  16. +22 −22 docs/howto/outputting-csv.txt
  17. +31 −31 docs/howto/outputting-pdf.txt
  18. +31 −31 docs/howto/static-files.txt
  19. +142 −142 docs/index.txt
  20. +77 −77 docs/internals/contributing/bugs-and-features.txt
  21. +62 −62 docs/internals/contributing/committing-code.txt
  22. +24 −24 docs/internals/contributing/index.txt
  23. +22 −22 docs/internals/contributing/translations.txt
  24. +121 −117 docs/internals/contributing/triaging-tickets.txt
  25. +35 −35 docs/internals/contributing/writing-code/branch-policy.txt
  26. +104 −104 docs/internals/contributing/writing-code/coding-style.txt
  27. +46 −46 docs/internals/contributing/writing-code/submitting-patches.txt
  28. +27 −27 docs/internals/contributing/writing-code/unit-tests.txt
  29. +130 −130 docs/internals/contributing/writing-documentation.txt
  30. +173 −173 docs/internals/deprecation.txt
  31. +52 −52 docs/internals/release-process.txt
  32. +9 −9 docs/intro/install.txt
  33. +6 −6 docs/intro/overview.txt
  34. +64 −64 docs/intro/tutorial01.txt
  35. +38 −38 docs/intro/tutorial02.txt
  36. +30 −30 docs/intro/tutorial03.txt
  37. +87 −87 docs/intro/tutorial04.txt
  38. +79 −79 docs/intro/whatsnext.txt
  39. +84 −84 docs/misc/api-stability.txt
  40. +2 −2 docs/misc/design-philosophies.txt
  41. +130 −130 docs/ref/class-based-views.txt
  42. +4 −4 docs/ref/contrib/admin/actions.txt
  43. +22 −22 docs/ref/contrib/admin/admindocs.txt
  44. +6 −6 docs/ref/contrib/comments/custom.txt
  45. +40 −40 docs/ref/contrib/comments/index.txt
  46. +42 −42 docs/ref/contrib/comments/signals.txt
  47. +20 −20 docs/ref/contrib/comments/upgrade.txt
  48. +38 −38 docs/ref/contrib/contenttypes.txt
  49. +33 −33 docs/ref/contrib/csrf.txt
  50. +26 −26 docs/ref/contrib/databrowse.txt
  51. +20 −20 docs/ref/contrib/flatpages.txt
  52. +42 −42 docs/ref/contrib/formtools/form-preview.txt
  53. +35 −35 docs/ref/contrib/formtools/form-wizard.txt
  54. +36 −36 docs/ref/contrib/humanize.txt
  55. +4 −4 docs/ref/contrib/markup.txt
  56. +14 −14 docs/ref/contrib/messages.txt
  57. +11 −11 docs/ref/contrib/redirects.txt
  58. +40 −40 docs/ref/contrib/sitemaps.txt
  59. +14 −14 docs/ref/contrib/sites.txt
  60. +10 −10 docs/ref/contrib/staticfiles.txt
  61. +82 −82 docs/ref/contrib/syndication.txt
  62. +15 −15 docs/ref/contrib/webdesign.txt
  63. +55 −55 docs/ref/databases.txt
  64. +81 −81 docs/ref/django-admin.txt
  65. +9 −9 docs/ref/exceptions.txt
  66. +27 −27 docs/ref/forms/api.txt
  67. +230 −229 docs/ref/forms/fields.txt
  68. +66 −66 docs/ref/forms/validation.txt
  69. +57 −74 docs/ref/forms/widgets.txt
  70. +494 −494 docs/ref/generic-views.txt
  71. +32 −32 docs/ref/middleware.txt
  72. +33 −33 docs/ref/models/fields.txt
  73. +41 −41 docs/ref/models/instances.txt
  74. +15 −15 docs/ref/models/options.txt
  75. +15 −15 docs/ref/models/relations.txt
  76. +39 −39 docs/ref/request-response.txt
  77. +27 −27 docs/ref/settings.txt
  78. +39 −46 docs/ref/signals.txt
  79. +6 −6 docs/ref/template-response.txt
  80. +108 −108 docs/ref/templates/api.txt
  81. +141 −141 docs/ref/templates/builtins.txt
  82. +48 −48 docs/ref/unicode.txt
  83. +12 −12 docs/ref/utils.txt
  84. +40 −40 docs/releases/0.95.txt
  85. +41 −41 docs/releases/0.96.txt
  86. +15 −15 docs/releases/1.0-porting-guide.txt
  87. +3 −3 docs/releases/1.1-alpha-1.txt
  88. +30 −30 docs/releases/1.1-beta-1.txt
  89. +3 −3 docs/releases/1.1-rc-1.txt
  90. +6 −6 docs/releases/1.1.4.txt
  91. +27 −27 docs/releases/1.1.txt
  92. +47 −47 docs/releases/1.2-alpha-1.txt
  93. +3 −3 docs/releases/1.2-beta-1.txt
  94. +3 −3 docs/releases/1.2-rc-1.txt
  95. +6 −6 docs/releases/1.2.5.txt
  96. +64 −64 docs/releases/1.2.txt
  97. +18 −18 docs/releases/1.3-alpha-1.txt
  98. +21 −21 docs/releases/1.3-beta-1.txt
  99. +36 −36 docs/releases/1.3.txt
  100. +85 −85 docs/topics/cache.txt
  101. +16 −16 docs/topics/class-based-views.txt
  102. +16 −16 docs/topics/conditional-view-processing.txt
  103. +20 −20 docs/topics/db/managers.txt
  104. +148 −148 docs/topics/db/models.txt
  105. +11 −11 docs/topics/db/optimization.txt
  106. +37 −37 docs/topics/db/queries.txt
  107. +18 −18 docs/topics/db/transactions.txt
  108. +83 −83 docs/topics/email.txt
  109. +34 −34 docs/topics/forms/index.txt
  110. +62 −62 docs/topics/forms/modelforms.txt
  111. +18 −18 docs/topics/generic-views-migration.txt
  112. +16 −16 docs/topics/generic-views.txt
  113. +88 −88 docs/topics/http/file-uploads.txt
  114. +13 −13 docs/topics/http/middleware.txt
  115. +40 −40 docs/topics/http/sessions.txt
  116. +25 −25 docs/topics/http/shortcuts.txt
  117. +88 −88 docs/topics/http/urls.txt
  118. +30 −30 docs/topics/http/views.txt
  119. +83 −83 docs/topics/i18n/deployment.txt
  120. +18 −18 docs/topics/i18n/index.txt
  121. +56 −56 docs/topics/i18n/internationalization.txt
  122. +23 −23 docs/topics/i18n/localization.txt
  123. +10 −10 docs/topics/install.txt
  124. +70 −71 docs/topics/logging.txt
  125. +9 −9 docs/topics/serialization.txt
  126. +10 −10 docs/topics/settings.txt
  127. +14 −14 docs/topics/signals.txt
  128. +6 −6 docs/topics/signing.txt
  129. +159 −159 docs/topics/testing.txt
20 docs/faq/admin.txt
View
@@ -8,16 +8,16 @@ The login cookie isn't being set correctly, because the domain of the cookie
sent out by Django doesn't match the domain in your browser. Try these two
things:
- * Set the :setting:`SESSION_COOKIE_DOMAIN` setting in your admin config
- file to match your domain. For example, if you're going to
- "http://www.example.com/admin/" in your browser, in
- "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.com'``.
-
- * Some browsers (Firefox?) don't like to accept cookies from domains that
- don't have dots in them. If you're running the admin site on "localhost"
- or another domain that doesn't have a dot in it, try going to
- "localhost.localdomain" or "127.0.0.1". And set
- :setting:`SESSION_COOKIE_DOMAIN` accordingly.
+* Set the :setting:`SESSION_COOKIE_DOMAIN` setting in your admin config
+ file to match your domain. For example, if you're going to
+ "http://www.example.com/admin/" in your browser, in
+ "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.com'``.
+
+* Some browsers (Firefox?) don't like to accept cookies from domains that
+ don't have dots in them. If you're running the admin site on "localhost"
+ or another domain that doesn't have a dot in it, try going to
+ "localhost.localdomain" or "127.0.0.1". And set
+ :setting:`SESSION_COOKIE_DOMAIN` accordingly.
I can't log in. When I enter a valid username and password, it brings up the login page again, with a "Please enter a correct username and password" error.
-----------------------------------------------------------------------------------------------------------------------------------------------------------
18 docs/faq/contributing.txt
View
@@ -26,17 +26,17 @@ The best way to make sure tickets do not get hung up on the way to checkin is
to make it dead easy, even for someone who may not be intimately familiar with
that area of the code, to understand the problem and verify the fix:
- * Are there clear instructions on how to reproduce the bug? If this
- touches a dependency (such as PIL), a contrib module, or a specific
- database, are those instructions clear enough even for someone not
- familiar with it?
+* Are there clear instructions on how to reproduce the bug? If this
+ touches a dependency (such as PIL), a contrib module, or a specific
+ database, are those instructions clear enough even for someone not
+ familiar with it?
- * If there are several patches attached to the ticket, is it clear what
- each one does, which ones can be ignored and which matter?
+* If there are several patches attached to the ticket, is it clear what
+ each one does, which ones can be ignored and which matter?
- * Does the patch include a unit test? If not, is there a very clear
- explanation why not? A test expresses succinctly what the problem is,
- and shows that the patch actually fixes it.
+* Does the patch include a unit test? If not, is there a very clear
+ explanation why not? A test expresses succinctly what the problem is,
+ and shows that the patch actually fixes it.
If your patch stands no chance of inclusion in Django, we won't ignore it --
we'll just close the ticket. So if your ticket is still open, it doesn't mean
10 docs/faq/install.txt
View
@@ -4,11 +4,11 @@ FAQ: Installation
How do I get started?
---------------------
- #. `Download the code`_.
- #. Install Django (read the :doc:`installation guide </intro/install>`).
- #. Walk through the :doc:`tutorial </intro/tutorial01>`.
- #. Check out the rest of the :doc:`documentation </index>`, and `ask questions`_ if you
- run into trouble.
+#. `Download the code`_.
+#. Install Django (read the :doc:`installation guide </intro/install>`).
+#. Walk through the :doc:`tutorial </intro/tutorial01>`.
+#. Check out the rest of the :doc:`documentation </index>`, and `ask questions`_ if you
+ run into trouble.
.. _`Download the code`: http://www.djangoproject.com/download/
.. _ask questions: http://www.djangoproject.com/community/
58 docs/faq/usage.txt
View
@@ -6,21 +6,21 @@ Why do I get an error about importing DJANGO_SETTINGS_MODULE?
Make sure that:
- * The environment variable DJANGO_SETTINGS_MODULE is set to a
- fully-qualified Python module (i.e. "mysite.settings").
+* The environment variable DJANGO_SETTINGS_MODULE is set to a
+ fully-qualified Python module (i.e. "mysite.settings").
- * Said module is on ``sys.path`` (``import mysite.settings`` should work).
+* Said module is on ``sys.path`` (``import mysite.settings`` should work).
- * The module doesn't contain syntax errors (of course).
+* The module doesn't contain syntax errors (of course).
- * If you're using mod_python but *not* using Django's request handler,
- you'll need to work around a mod_python bug related to the use of
- ``SetEnv``; before you import anything from Django you'll need to do
- the following::
+* If you're using mod_python but *not* using Django's request handler,
+ you'll need to work around a mod_python bug related to the use of
+ ``SetEnv``; before you import anything from Django you'll need to do
+ the following::
- os.environ.update(req.subprocess_env)
+ os.environ.update(req.subprocess_env)
- (where ``req`` is the mod_python request object).
+ (where ``req`` is the mod_python request object).
I can't stand your template language. Do I have to use it?
----------------------------------------------------------
@@ -46,25 +46,25 @@ How do I use image and file fields?
Using a :class:`~django.db.models.FileField` or an
:class:`~django.db.models.ImageField` in a model takes a few steps:
- #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as
- the full path to a directory where you'd like Django to store uploaded
- files. (For performance, these files are not stored in the database.)
- Define :setting:`MEDIA_URL` as the base public URL of that directory.
- Make sure that this directory is writable by the Web server's user
- account.
-
- #. Add the :class:`~django.db.models.FileField` or
- :class:`~django.db.models.ImageField` to your model, making sure to
- define the :attr:`~django.db.models.FileField.upload_to` option to tell
- Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload
- files.
-
- #. All that will be stored in your database is a path to the file
- (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
- convenience :attr:`~django.core.files.File.url` attribute provided by
- Django. For example, if your :class:`~django.db.models.ImageField` is
- called ``mug_shot``, you can get the absolute path to your image in a
- template with ``{{ object.mug_shot.url }}``.
+#. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as
+ the full path to a directory where you'd like Django to store uploaded
+ files. (For performance, these files are not stored in the database.)
+ Define :setting:`MEDIA_URL` as the base public URL of that directory.
+ Make sure that this directory is writable by the Web server's user
+ account.
+
+#. Add the :class:`~django.db.models.FileField` or
+ :class:`~django.db.models.ImageField` to your model, making sure to
+ define the :attr:`~django.db.models.FileField.upload_to` option to tell
+ Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload
+ files.
+
+#. All that will be stored in your database is a path to the file
+ (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
+ convenience :attr:`~django.core.files.File.url` attribute provided by
+ Django. For example, if your :class:`~django.db.models.ImageField` is
+ called ``mug_shot``, you can get the absolute path to your image in a
+ template with ``{{ object.mug_shot.url }}``.
How do I make a variable available to all my templates?
-------------------------------------------------------
44 docs/howto/apache-auth.txt
View
@@ -14,12 +14,12 @@ dealing with Apache, you can configuring Apache to authenticate against Django's
:doc:`authentication system </topics/auth>` directly. For example, you
could:
- * Serve static/media files directly from Apache only to authenticated users.
+* Serve static/media files directly from Apache only to authenticated users.
- * Authenticate access to a Subversion_ repository against Django users with
- a certain permission.
+* Authenticate access to a Subversion_ repository against Django users with
+ a certain permission.
- * Allow certain users to connect to a WebDAV share created with mod_dav_.
+* Allow certain users to connect to a WebDAV share created with mod_dav_.
.. _Subversion: http://subversion.tigris.org/
.. _mod_dav: http://httpd.apache.org/docs/2.0/mod/mod_dav.html
@@ -93,29 +93,29 @@ By default, the authentication handler will limit access to the ``/example/``
location to users marked as staff members. You can use a set of
``PythonOption`` directives to modify this behavior:
- ================================ =========================================
- ``PythonOption`` Explanation
- ================================ =========================================
- ``DjangoRequireStaffStatus`` If set to ``on`` only "staff" users (i.e.
- those with the ``is_staff`` flag set)
- will be allowed.
+================================ =========================================
+``PythonOption`` Explanation
+================================ =========================================
+``DjangoRequireStaffStatus`` If set to ``on`` only "staff" users (i.e.
+ those with the ``is_staff`` flag set)
+ will be allowed.
- Defaults to ``on``.
+ Defaults to ``on``.
- ``DjangoRequireSuperuserStatus`` If set to ``on`` only superusers (i.e.
- those with the ``is_superuser`` flag set)
- will be allowed.
+``DjangoRequireSuperuserStatus`` If set to ``on`` only superusers (i.e.
+ those with the ``is_superuser`` flag set)
+ will be allowed.
- Defaults to ``off``.
+ Defaults to ``off``.
- ``DjangoPermissionName`` The name of a permission to require for
- access. See :ref:`custom permissions
- <custom-permissions>` for more
- information.
+``DjangoPermissionName`` The name of a permission to require for
+ access. See :ref:`custom permissions
+ <custom-permissions>` for more
+ information.
- By default no specific permission will be
- required.
- ================================ =========================================
+ By default no specific permission will be
+ required.
+================================ =========================================
Note that sometimes ``SetEnv`` doesn't play well in this mod_python
configuration, for reasons unknown. If you're having problems getting
10 docs/howto/custom-file-storage.txt
View
@@ -37,11 +37,11 @@ You'll need to follow these steps:
Your custom storage system may override any of the storage methods explained in
:doc:`/ref/files/storage`, but you **must** implement the following methods:
- * :meth:`Storage.delete`
- * :meth:`Storage.exists`
- * :meth:`Storage.listdir`
- * :meth:`Storage.size`
- * :meth:`Storage.url`
+* :meth:`Storage.delete`
+* :meth:`Storage.exists`
+* :meth:`Storage.listdir`
+* :meth:`Storage.size`
+* :meth:`Storage.url`
You'll also usually want to use hooks specifically designed for custom storage
objects. These are:
120 docs/howto/custom-model-fields.txt
View
@@ -133,14 +133,14 @@ example). If this sounds a bit tricky, don't worry -- it will become clearer in
the examples below. Just remember that you will often end up creating two
classes when you want a custom field:
- * The first class is the Python object that your users will manipulate.
- They will assign it to the model attribute, they will read from it for
- displaying purposes, things like that. This is the ``Hand`` class in our
- example.
+* The first class is the Python object that your users will manipulate.
+ They will assign it to the model attribute, they will read from it for
+ displaying purposes, things like that. This is the ``Hand`` class in our
+ example.
- * The second class is the ``Field`` subclass. This is the class that knows
- how to convert your first class back and forth between its permanent
- storage form and the Python form.
+* The second class is the ``Field`` subclass. This is the class that knows
+ how to convert your first class back and forth between its permanent
+ storage form and the Python form.
Writing a field subclass
========================
@@ -198,33 +198,33 @@ card values plus their suits; 104 characters in total.
The :meth:`~django.db.models.Field.__init__` method takes the following
parameters:
- * :attr:`~django.db.models.Field.verbose_name`
- * :attr:`~django.db.models.Field.name`
- * :attr:`~django.db.models.Field.primary_key`
- * :attr:`~django.db.models.Field.max_length`
- * :attr:`~django.db.models.Field.unique`
- * :attr:`~django.db.models.Field.blank`
- * :attr:`~django.db.models.Field.null`
- * :attr:`~django.db.models.Field.db_index`
- * :attr:`~django.db.models.Field.rel`: Used for related fields (like
- :class:`ForeignKey`). For advanced use only.
- * :attr:`~django.db.models.Field.default`
- * :attr:`~django.db.models.Field.editable`
- * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
- not be serialized when the model is passed to Django's :doc:`serializers
- </topics/serialization>`. Defaults to ``True``.
- * :attr:`~django.db.models.Field.unique_for_date`
- * :attr:`~django.db.models.Field.unique_for_month`
- * :attr:`~django.db.models.Field.unique_for_year`
- * :attr:`~django.db.models.Field.choices`
- * :attr:`~django.db.models.Field.help_text`
- * :attr:`~django.db.models.Field.db_column`
- * :attr:`~django.db.models.Field.db_tablespace`: Currently only used with
- the Oracle backend and only for index creation. You can usually ignore
- this option.
- * :attr:`~django.db.models.Field.auto_created`: True if the field was
- automatically created, as for the `OneToOneField` used by model
- inheritance. For advanced use only.
+* :attr:`~django.db.models.Field.verbose_name`
+* :attr:`~django.db.models.Field.name`
+* :attr:`~django.db.models.Field.primary_key`
+* :attr:`~django.db.models.Field.max_length`
+* :attr:`~django.db.models.Field.unique`
+* :attr:`~django.db.models.Field.blank`
+* :attr:`~django.db.models.Field.null`
+* :attr:`~django.db.models.Field.db_index`
+* :attr:`~django.db.models.Field.rel`: Used for related fields (like
+ :class:`ForeignKey`). For advanced use only.
+* :attr:`~django.db.models.Field.default`
+* :attr:`~django.db.models.Field.editable`
+* :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
+ not be serialized when the model is passed to Django's :doc:`serializers
+ </topics/serialization>`. Defaults to ``True``.
+* :attr:`~django.db.models.Field.unique_for_date`
+* :attr:`~django.db.models.Field.unique_for_month`
+* :attr:`~django.db.models.Field.unique_for_year`
+* :attr:`~django.db.models.Field.choices`
+* :attr:`~django.db.models.Field.help_text`
+* :attr:`~django.db.models.Field.db_column`
+* :attr:`~django.db.models.Field.db_tablespace`: Currently only used with
+ the Oracle backend and only for index creation. You can usually ignore
+ this option.
+* :attr:`~django.db.models.Field.auto_created`: True if the field was
+ automatically created, as for the `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
@@ -415,11 +415,11 @@ that are more complex than strings, dates, integers or floats, then you'll need
to override this method. As a general rule, the method should deal gracefully
with any of the following arguments:
- * An instance of the correct type (e.g., ``Hand`` in our ongoing example).
+* An instance of the correct type (e.g., ``Hand`` in our ongoing example).
- * A string (e.g., from a deserializer).
+* A string (e.g., from a deserializer).
- * Whatever the database returns for the column type you're using.
+* Whatever the database returns for the column type you're using.
In our ``HandField`` class, we're storing the data as a VARCHAR field in the
database, so we need to be able to process strings and ``Hand`` instances in
@@ -695,19 +695,19 @@ complex conversions between your Python types and your database and
serialization formats. Here are a couple of tips to make things go more
smoothly:
- 1. Look at the existing Django fields (in
- :file:`django/db/models/fields/__init__.py`) for inspiration. Try to find
- a field that's similar to what you want and extend it a little bit,
- instead of creating an entirely new field from scratch.
+1. Look at the existing Django fields (in
+ :file:`django/db/models/fields/__init__.py`) for inspiration. Try to find
+ a field that's similar to what you want and extend it a little bit,
+ instead of creating an entirely new field from scratch.
- 2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're
- wrapping up as a field. There are a lot of places where the default
- behavior of the field code is to call
- :func:`~django.utils.encoding.force_unicode` on the value. (In our
- examples in this document, ``value`` would be a ``Hand`` instance, not a
- ``HandField``). So if your :meth:`__unicode__` method automatically
- converts to the string form of your Python object, you can save yourself
- a lot of work.
+2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're
+ wrapping up as a field. There are a lot of places where the default
+ behavior of the field code is to call
+ :func:`~django.utils.encoding.force_unicode` on the value. (In our
+ examples in this document, ``value`` would be a ``Hand`` instance, not a
+ ``HandField``). So if your :meth:`__unicode__` method automatically
+ converts to the string form of your Python object, you can save yourself
+ a lot of work.
Writing a ``FileField`` subclass
@@ -735,14 +735,14 @@ A few suggestions
In addition to the above details, there are a few guidelines which can greatly
improve the efficiency and readability of the field's code.
- 1. The source for Django's own ``ImageField`` (in
- ``django/db/models/fields/files.py``) is a great example of how to
- subclass ``FileField`` to support a particular type of file, as it
- incorporates all of the techniques described above.
-
- 2. Cache file attributes wherever possible. Since files may be stored in
- remote storage systems, retrieving them may cost extra time, or even
- money, that isn't always necessary. Once a file is retrieved to obtain
- some data about its content, cache as much of that data as possible to
- reduce the number of times the file must be retrieved on subsequent
- calls for that information.
+1. The source for Django's own ``ImageField`` (in
+ ``django/db/models/fields/files.py``) is a great example of how to
+ subclass ``FileField`` to support a particular type of file, as it
+ incorporates all of the techniques described above.
+
+2. Cache file attributes wherever possible. Since files may be stored in
+ remote storage systems, retrieving them may cost extra time, or even
+ money, that isn't always necessary. Once a file is retrieved to obtain
+ some data about its content, cache as much of that data as possible to
+ reduce the number of times the file must be retrieved on subsequent
+ calls for that information.
404 docs/howto/custom-template-tags.txt
View
@@ -77,9 +77,9 @@ Writing custom template filters
Custom filters are just Python functions that take one or two arguments:
- * The value of the variable (input) -- not necessarily a string.
- * The value of the argument -- this can have a default value, or be left
- out altogether.
+* The value of the variable (input) -- not necessarily a string.
+* The value of the argument -- this can have a default value, or be left
+ out altogether.
For example, in the filter ``{{ var|foo:"bar" }}``, the filter ``foo`` would be
passed the variable ``var`` and the argument ``"bar"``.
@@ -124,9 +124,9 @@ your ``Library`` instance, to make it available to Django's template language:
The ``Library.filter()`` method takes two arguments:
- 1. The name of the filter -- a string.
- 2. The compilation function -- a Python function (not the name of the
- function as a string).
+1. The name of the filter -- a string.
+2. The compilation function -- a Python function (not the name of the
+ function as a string).
You can use ``register.filter()`` as a decorator instead:
@@ -173,156 +173,156 @@ When writing a custom filter, give some thought to how the filter will interact
with Django's auto-escaping behavior. Note that three types of strings can be
passed around inside the template code:
- * **Raw strings** are the native Python ``str`` or ``unicode`` types. On
- output, they're escaped if auto-escaping is in effect and presented
- unchanged, otherwise.
+* **Raw strings** are the native Python ``str`` or ``unicode`` types. On
+ output, they're escaped if auto-escaping is in effect and presented
+ unchanged, otherwise.
- * **Safe strings** are strings that have been marked safe from further
- escaping at output time. Any necessary escaping has already been done.
- They're commonly used for output that contains raw HTML that is intended
- to be interpreted as-is on the client side.
+* **Safe strings** are strings that have been marked safe from further
+ escaping at output time. Any necessary escaping has already been done.
+ They're commonly used for output that contains raw HTML that is intended
+ to be interpreted as-is on the client side.
- Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
- They share a common base class of ``SafeData``, so you can test
- for them using code like:
+ Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
+ They share a common base class of ``SafeData``, so you can test
+ for them using code like:
- .. code-block:: python
+ .. code-block:: python
- if isinstance(value, SafeData):
- # Do something with the "safe" string.
- ...
+ if isinstance(value, SafeData):
+ # Do something with the "safe" string.
+ ...
- * **Strings marked as "needing escaping"** are *always* escaped on
- output, regardless of whether they are in an :ttag:`autoescape` block or
- not. These strings are only escaped once, however, even if auto-escaping
- applies.
+* **Strings marked as "needing escaping"** are *always* escaped on
+ output, regardless of whether they are in an :ttag:`autoescape` block or
+ not. These strings are only escaped once, however, even if auto-escaping
+ applies.
- Internally, these strings are of type ``EscapeString`` or
- ``EscapeUnicode``. Generally you don't have to worry about these; they
- exist for the implementation of the :tfilter:`escape` filter.
+ Internally, these strings are of type ``EscapeString`` or
+ ``EscapeUnicode``. Generally you don't have to worry about these; they
+ exist for the implementation of the :tfilter:`escape` filter.
Template filter code falls into one of two situations:
- 1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``,
- ``'``, ``"`` or ``&``) into the result that were not already present. In
- this case, you can let Django take care of all the auto-escaping
- handling for you. All you need to do is put the ``is_safe`` attribute on
- your filter function and set it to ``True``, like so:
-
- .. code-block:: python
-
- @register.filter
- def myfilter(value):
- return value
- myfilter.is_safe = True
-
- This attribute tells Django that if a "safe" string is passed into your
- filter, the result will still be "safe" and if a non-safe string is
- passed in, Django will automatically escape it, if necessary.
-
- You can think of this as meaning "this filter is safe -- it doesn't
- introduce any possibility of unsafe HTML."
-
- The reason ``is_safe`` is necessary is because there are plenty of
- normal string operations that will turn a ``SafeData`` object back into
- a normal ``str`` or ``unicode`` object and, rather than try to catch
- them all, which would be very difficult, Django repairs the damage after
- the filter has completed.
-
- For example, suppose you have a filter that adds the string ``xx`` to
- the end of any input. Since this introduces no dangerous HTML characters
- to the result (aside from any that were already present), you should
- mark your filter with ``is_safe``:
-
- .. code-block:: python
-
- @register.filter
- def add_xx(value):
- return '%sxx' % value
- add_xx.is_safe = True
-
- When this filter is used in a template where auto-escaping is enabled,
- Django will escape the output whenever the input is not already marked
- as "safe".
-
- By default, ``is_safe`` defaults to ``False``, and you can omit it from
- any filters where it isn't required.
-
- Be careful when deciding if your filter really does leave safe strings
- as safe. If you're *removing* characters, you might inadvertently leave
- unbalanced HTML tags or entities in the result. For example, removing a
- ``>`` from the input might turn ``<a>`` into ``<a``, which would need to
- be escaped on output to avoid causing problems. Similarly, removing a
- semicolon (``;``) can turn ``&amp;`` into ``&amp``, which is no longer a
- valid entity and thus needs further escaping. Most cases won't be nearly
- this tricky, but keep an eye out for any problems like that when
- reviewing your code.
-
- Marking a filter ``is_safe`` will coerce the filter's return value to
- a string. If your filter should return a boolean or other non-string
- value, marking it ``is_safe`` will probably have unintended
- consequences (such as converting a boolean False to the string
- 'False').
-
- 2. Alternatively, your filter code can manually take care of any necessary
- escaping. This is necessary when you're introducing new HTML markup into
- the result. You want to mark the output as safe from further
- escaping so that your HTML markup isn't escaped further, so you'll need
- to handle the input yourself.
-
- To mark the output as a safe string, use
- :func:`django.utils.safestring.mark_safe`.
-
- Be careful, though. You need to do more than just mark the output as
- safe. You need to ensure it really *is* safe, and what you do depends on
- whether auto-escaping is in effect. The idea is to write filters than
- can operate in templates where auto-escaping is either on or off in
- order to make things easier for your template authors.
-
- In order for your filter to know the current auto-escaping state, set
- the ``needs_autoescape`` attribute to ``True`` on your function. (If you
- don't specify this attribute, it defaults to ``False``). This attribute
- tells Django that your filter function wants to be passed an extra
- keyword argument, called ``autoescape``, that is ``True`` if
- auto-escaping is in effect and ``False`` otherwise.
-
- For example, let's write a filter that emphasizes the first character of
- a string:
-
- .. code-block:: python
-
- from django.utils.html import conditional_escape
- from django.utils.safestring import mark_safe
-
- def initial_letter_filter(text, autoescape=None):
- first, other = text[0], text[1:]
- if autoescape:
- esc = conditional_escape
- else:
- esc = lambda x: x
- result = '<strong>%s</strong>%s' % (esc(first), esc(other))
- return mark_safe(result)
- initial_letter_filter.needs_autoescape = True
-
- The ``needs_autoescape`` attribute on the filter function and the
- ``autoescape`` keyword argument mean that our function will know whether
- automatic escaping is in effect when the filter is called. We use
- ``autoescape`` to decide whether the input data needs to be passed
- through ``django.utils.html.conditional_escape`` or not. (In the latter
- case, we just use the identity function as the "escape" function.) The
- ``conditional_escape()`` function is like ``escape()`` except it only
- escapes input that is **not** a ``SafeData`` instance. If a ``SafeData``
- instance is passed to ``conditional_escape()``, the data is returned
- unchanged.
-
- Finally, in the above example, we remember to mark the result as safe
- so that our HTML is inserted directly into the template without further
- escaping.
-
- There's no need to worry about the ``is_safe`` attribute in this case
- (although including it wouldn't hurt anything). Whenever you manually
- handle the auto-escaping issues and return a safe string, the
- ``is_safe`` attribute won't change anything either way.
+1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``,
+ ``'``, ``"`` or ``&``) into the result that were not already present. In
+ this case, you can let Django take care of all the auto-escaping
+ handling for you. All you need to do is put the ``is_safe`` attribute on
+ your filter function and set it to ``True``, like so:
+
+ .. code-block:: python
+
+ @register.filter
+ def myfilter(value):
+ return value
+ myfilter.is_safe = True
+
+ This attribute tells Django that if a "safe" string is passed into your
+ filter, the result will still be "safe" and if a non-safe string is
+ passed in, Django will automatically escape it, if necessary.
+
+ You can think of this as meaning "this filter is safe -- it doesn't
+ introduce any possibility of unsafe HTML."
+
+ The reason ``is_safe`` is necessary is because there are plenty of
+ normal string operations that will turn a ``SafeData`` object back into
+ a normal ``str`` or ``unicode`` object and, rather than try to catch
+ them all, which would be very difficult, Django repairs the damage after
+ the filter has completed.
+
+ For example, suppose you have a filter that adds the string ``xx`` to
+ the end of any input. Since this introduces no dangerous HTML characters
+ to the result (aside from any that were already present), you should
+ mark your filter with ``is_safe``:
+
+ .. code-block:: python
+
+ @register.filter
+ def add_xx(value):
+ return '%sxx' % value
+ add_xx.is_safe = True
+
+ When this filter is used in a template where auto-escaping is enabled,
+ Django will escape the output whenever the input is not already marked
+ as "safe".
+
+ By default, ``is_safe`` defaults to ``False``, and you can omit it from
+ any filters where it isn't required.
+
+ Be careful when deciding if your filter really does leave safe strings
+ as safe. If you're *removing* characters, you might inadvertently leave
+ unbalanced HTML tags or entities in the result. For example, removing a
+ ``>`` from the input might turn ``<a>`` into ``<a``, which would need to
+ be escaped on output to avoid causing problems. Similarly, removing a
+ semicolon (``;``) can turn ``&amp;`` into ``&amp``, which is no longer a
+ valid entity and thus needs further escaping. Most cases won't be nearly
+ this tricky, but keep an eye out for any problems like that when
+ reviewing your code.
+
+ Marking a filter ``is_safe`` will coerce the filter's return value to
+ a string. If your filter should return a boolean or other non-string
+ value, marking it ``is_safe`` will probably have unintended
+ consequences (such as converting a boolean False to the string
+ 'False').
+
+2. Alternatively, your filter code can manually take care of any necessary
+ escaping. This is necessary when you're introducing new HTML markup into
+ the result. You want to mark the output as safe from further
+ escaping so that your HTML markup isn't escaped further, so you'll need
+ to handle the input yourself.
+
+ To mark the output as a safe string, use
+ :func:`django.utils.safestring.mark_safe`.
+
+ Be careful, though. You need to do more than just mark the output as
+ safe. You need to ensure it really *is* safe, and what you do depends on
+ whether auto-escaping is in effect. The idea is to write filters than
+ can operate in templates where auto-escaping is either on or off in
+ order to make things easier for your template authors.
+
+ In order for your filter to know the current auto-escaping state, set
+ the ``needs_autoescape`` attribute to ``True`` on your function. (If you
+ don't specify this attribute, it defaults to ``False``). This attribute
+ tells Django that your filter function wants to be passed an extra
+ keyword argument, called ``autoescape``, that is ``True`` if
+ auto-escaping is in effect and ``False`` otherwise.
+
+ For example, let's write a filter that emphasizes the first character of
+ a string:
+
+ .. code-block:: python
+
+ from django.utils.html import conditional_escape
+ from django.utils.safestring import mark_safe
+
+ def initial_letter_filter(text, autoescape=None):
+ first, other = text[0], text[1:]
+ if autoescape:
+ esc = conditional_escape
+ else:
+ esc = lambda x: x
+ result = '<strong>%s</strong>%s' % (esc(first), esc(other))
+ return mark_safe(result)
+ initial_letter_filter.needs_autoescape = True
+
+ The ``needs_autoescape`` attribute on the filter function and the
+ ``autoescape`` keyword argument mean that our function will know whether
+ automatic escaping is in effect when the filter is called. We use
+ ``autoescape`` to decide whether the input data needs to be passed
+ through ``django.utils.html.conditional_escape`` or not. (In the latter
+ case, we just use the identity function as the "escape" function.) The
+ ``conditional_escape()`` function is like ``escape()`` except it only
+ escapes input that is **not** a ``SafeData`` instance. If a ``SafeData``
+ instance is passed to ``conditional_escape()``, the data is returned
+ unchanged.
+
+ Finally, in the above example, we remember to mark the result as safe
+ so that our HTML is inserted directly into the template without further
+ escaping.
+
+ There's no need to worry about the ``is_safe`` attribute in this case
+ (although including it wouldn't hurt anything). Whenever you manually
+ handle the auto-escaping issues and return a safe string, the
+ ``is_safe`` attribute won't change anything either way.
Writing custom template tags
----------------------------
@@ -381,37 +381,37 @@ object:
Notes:
- * ``parser`` is the template parser object. We don't need it in this
- example.
+* ``parser`` is the template parser object. We don't need it in this
+ example.
- * ``token.contents`` is a string of the raw contents of the tag. In our
- example, it's ``'current_time "%Y-%m-%d %I:%M %p"'``.
+* ``token.contents`` is a string of the raw contents of the tag. In our
+ example, it's ``'current_time "%Y-%m-%d %I:%M %p"'``.
- * The ``token.split_contents()`` method separates the arguments on spaces
- while keeping quoted strings together. The more straightforward
- ``token.contents.split()`` wouldn't be as robust, as it would naively
- split on *all* spaces, including those within quoted strings. It's a good
- idea to always use ``token.split_contents()``.
+* The ``token.split_contents()`` method separates the arguments on spaces
+ while keeping quoted strings together. The more straightforward
+ ``token.contents.split()`` wouldn't be as robust, as it would naively
+ split on *all* spaces, including those within quoted strings. It's a good
+ idea to always use ``token.split_contents()``.
- * This function is responsible for raising
- ``django.template.TemplateSyntaxError``, with helpful messages, for
- any syntax error.
+* This function is responsible for raising
+ ``django.template.TemplateSyntaxError``, with helpful messages, for
+ any syntax error.
- * The ``TemplateSyntaxError`` exceptions use the ``tag_name`` variable.
- Don't hard-code the tag's name in your error messages, because that
- couples the tag's name to your function. ``token.contents.split()[0]``
- will ''always'' be the name of your tag -- even when the tag has no
- arguments.
+* The ``TemplateSyntaxError`` exceptions use the ``tag_name`` variable.
+ Don't hard-code the tag's name in your error messages, because that
+ couples the tag's name to your function. ``token.contents.split()[0]``
+ will ''always'' be the name of your tag -- even when the tag has no
+ arguments.
- * The function returns a ``CurrentTimeNode`` with everything the node needs
- to know about this tag. In this case, it just passes the argument --
- ``"%Y-%m-%d %I:%M %p"``. The leading and trailing quotes from the
- template tag are removed in ``format_string[1:-1]``.
+* The function returns a ``CurrentTimeNode`` with everything the node needs
+ to know about this tag. In this case, it just passes the argument --
+ ``"%Y-%m-%d %I:%M %p"``. The leading and trailing quotes from the
+ template tag are removed in ``format_string[1:-1]``.
- * The parsing is very low-level. The Django developers have experimented
- with writing small frameworks on top of this parsing system, using
- techniques such as EBNF grammars, but those experiments made the template
- engine too slow. It's low-level because that's fastest.
+* The parsing is very low-level. The Django developers have experimented
+ with writing small frameworks on top of this parsing system, using
+ techniques such as EBNF grammars, but those experiments made the template
+ engine too slow. It's low-level because that's fastest.
Writing the renderer
~~~~~~~~~~~~~~~~~~~~
@@ -433,14 +433,14 @@ Continuing the above example, we need to define ``CurrentTimeNode``:
Notes:
- * ``__init__()`` gets the ``format_string`` from ``do_current_time()``.
- Always pass any options/parameters/arguments to a ``Node`` via its
- ``__init__()``.
+* ``__init__()`` gets the ``format_string`` from ``do_current_time()``.
+ Always pass any options/parameters/arguments to a ``Node`` via its
+ ``__init__()``.
- * The ``render()`` method is where the work actually happens.
+* The ``render()`` method is where the work actually happens.
- * ``render()`` should never raise ``TemplateSyntaxError`` or any other
- exception. It should fail silently, just as template filters should.
+* ``render()`` should never raise ``TemplateSyntaxError`` or any other
+ exception. It should fail silently, just as template filters should.
Ultimately, this decoupling of compilation and rendering results in an
efficient template system, because a template can render multiple contexts
@@ -525,14 +525,14 @@ A naive implementation of ``CycleNode`` might look something like this:
But, suppose we have two templates rendering the template snippet from above at
the same time:
- 1. Thread 1 performs its first loop iteration, ``CycleNode.render()``
- returns 'row1'
- 2. Thread 2 performs its first loop iteration, ``CycleNode.render()``
- returns 'row2'
- 3. Thread 1 performs its second loop iteration, ``CycleNode.render()``
- returns 'row1'
- 4. Thread 2 performs its second loop iteration, ``CycleNode.render()``
- returns 'row2'
+1. Thread 1 performs its first loop iteration, ``CycleNode.render()``
+ returns 'row1'
+2. Thread 2 performs its first loop iteration, ``CycleNode.render()``
+ returns 'row2'
+3. Thread 1 performs its second loop iteration, ``CycleNode.render()``
+ returns 'row1'
+4. Thread 2 performs its second loop iteration, ``CycleNode.render()``
+ returns 'row2'
The CycleNode is iterating, but it's iterating globally. As far as Thread 1
and Thread 2 are concerned, it's always returning the same value. This is
@@ -584,10 +584,10 @@ in "Writing custom template filters" above. Example:
The ``tag()`` method takes two arguments:
- 1. The name of the template tag -- a string. If this is left out, the
- name of the compilation function will be used.
- 2. The compilation function -- a Python function (not the name of the
- function as a string).
+1. The name of the template tag -- a string. If this is left out, the
+ name of the compilation function will be used.
+2. The compilation function -- a Python function (not the name of the
+ function as a string).
As with filter registration, it is also possible to use this as a decorator:
@@ -623,12 +623,12 @@ tag format that date-time:
Initially, ``token.split_contents()`` will return three values:
- 1. The tag name ``format_time``.
- 2. The string ``"blog_entry.date_updated"`` (without the surrounding
- quotes).
- 3. The formatting string ``"%Y-%m-%d %I:%M %p"``. The return value from
- ``split_contents()`` will include the leading and trailing quotes for
- string literals like this.
+1. The tag name ``format_time``.
+2. The string ``"blog_entry.date_updated"`` (without the surrounding
+ quotes).
+3. The formatting string ``"%Y-%m-%d %I:%M %p"``. The return value from
+ ``split_contents()`` will include the leading and trailing quotes for
+ string literals like this.
Now your tag should begin to look like this:
@@ -706,12 +706,12 @@ The decorator syntax also works:
A few things to note about the ``simple_tag`` helper function:
- * Checking for the required number of arguments, etc., has already been
- done by the time our function is called, so we don't need to do that.
- * The quotes around the argument (if any) have already been stripped away,
- so we just receive a plain string.
- * If the argument was a template variable, our function is passed the
- current value of the variable, not the variable itself.
+* Checking for the required number of arguments, etc., has already been
+ done by the time our function is called, so we don't need to do that.
+* The quotes around the argument (if any) have already been stripped away,
+ so we just receive a plain string.
+* If the argument was a template variable, our function is passed the
+ current value of the variable, not the variable itself.
.. versionadded:: 1.3
6 docs/howto/deployment/fastcgi.txt
View
@@ -168,9 +168,9 @@ Once you've got that set up, point Apache at your Django FastCGI instance by
editing the ``httpd.conf`` (Apache configuration) file. You'll need to do two
things:
- * Use the ``FastCGIExternalServer`` directive to specify the location of
- your FastCGI server.
- * Use ``mod_rewrite`` to point URLs at FastCGI as appropriate.
+* Use the ``FastCGIExternalServer`` directive to specify the location of
+ your FastCGI server.
+* Use ``mod_rewrite`` to point URLs at FastCGI as appropriate.
.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html
34 docs/howto/deployment/modpython.txt
View
@@ -240,11 +240,11 @@ server you choose.
We recommend using a separate Web server -- i.e., one that's not also running
Django -- for serving media. Here are some good choices:
- * lighttpd_
- * Nginx_
- * TUX_
- * A stripped-down version of Apache_
- * Cherokee_
+* lighttpd_
+* Nginx_
+* TUX_
+* A stripped-down version of Apache_
+* Cherokee_
If, however, you have no option but to serve media or static files on the
same Apache ``VirtualHost`` as Django, here's how you can turn off mod_python
@@ -299,11 +299,11 @@ Django distribution.
We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle
the admin files, but here are two other approaches:
- 1. Create a symbolic link to the admin static files from within your
- document root.
+1. Create a symbolic link to the admin static files from within your
+ document root.
- 2. Or, copy the admin static files so that they live within your Apache
- document root.
+2. Or, copy the admin static files so that they live within your Apache
+ document root.
Using "eggs" with mod_python
============================
@@ -362,15 +362,15 @@ If you get a segmentation fault
If Apache causes a segmentation fault, there are two probable causes, neither
of which has to do with Django itself.
- 1. It may be because your Python code is importing the "pyexpat" module,
- which may conflict with the version embedded in Apache. For full
- information, see `Expat Causing Apache Crash`_.
+1. It may be because your Python code is importing the "pyexpat" module,
+ which may conflict with the version embedded in Apache. For full
+ information, see `Expat Causing Apache Crash`_.
- 2. It may be because you're running mod_python and mod_php in the same
- Apache instance, with MySQL as your database backend. In some cases,
- this causes a known mod_python issue due to version conflicts in PHP and
- the Python MySQL backend. There's full information in the
- `mod_python FAQ entry`_.
+2. It may be because you're running mod_python and mod_php in the same
+ Apache instance, with MySQL as your database backend. In some cases,
+ this causes a known mod_python issue due to version conflicts in PHP and
+ the Python MySQL backend. There's full information in the
+ `mod_python FAQ entry`_.
If you continue to have problems setting up mod_python, a good thing to do is
get a barebones mod_python site working, without the Django framework. This is
18 docs/howto/deployment/modwsgi.txt
View
@@ -64,11 +64,11 @@ server you choose.
We recommend using a separate Web server -- i.e., one that's not also running
Django -- for serving media. Here are some good choices:
- * lighttpd_
- * Nginx_
- * TUX_
- * A stripped-down version of Apache_
- * Cherokee_
+* lighttpd_
+* Nginx_
+* TUX_
+* A stripped-down version of Apache_
+* Cherokee_
If, however, you have no option but to serve media files on the same Apache
``VirtualHost`` as Django, you can set up Apache to serve some URLs as
@@ -131,11 +131,11 @@ Django distribution.
We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle
the admin files, but here are two other approaches:
- 1. Create a symbolic link to the admin static files from within your
- document root.
+1. Create a symbolic link to the admin static files from within your
+ document root.
- 2. Or, copy the admin static files so that they live within your Apache
- document root.
+2. Or, copy the admin static files so that they live within your Apache
+ document root.
Details
=======
84 docs/howto/error-reporting.txt
View
@@ -56,12 +56,12 @@ setting.
Django can also be configured to email errors about broken links (404 "page
not found" errors). Django sends emails about 404 errors when:
- * :setting:`DEBUG` is ``False``
+* :setting:`DEBUG` is ``False``
- * :setting:`SEND_BROKEN_LINK_EMAILS` is ``True``
+* :setting:`SEND_BROKEN_LINK_EMAILS` is ``True``
- * Your :setting:`MIDDLEWARE_CLASSES` setting includes ``CommonMiddleware``
- (which it does by default).
+* Your :setting:`MIDDLEWARE_CLASSES` setting includes ``CommonMiddleware``
+ (which it does by default).
If those conditions are met, Django will email the users listed in the
:setting:`MANAGERS` setting whenever your code raises a 404 and the request has
@@ -144,18 +144,16 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
If a function (either a view or any regular callback) in your code uses
local variables susceptible to contain sensitive information, you may
prevent the values of those variables from being included in error reports
- using the ``sensitive_variables`` decorator:
+ using the ``sensitive_variables`` decorator::
- .. code-block:: python
+ from django.views.decorators.debug import sensitive_variables
- from django.views.decorators.debug import sensitive_variables
-
- @sensitive_variables('user', 'pw', 'cc')
- def process_info(user):
- pw = user.pass_word
- cc = user.credit_card_number
- name = user.name
- ...
+ @sensitive_variables('user', 'pw', 'cc')
+ def process_info(user):
+ pw = user.pass_word
+ cc = user.credit_card_number
+ name = user.name
+ ...
In the above example, the values for the ``user``, ``pw`` and ``cc``
variables will be hidden and replaced with stars (`**********`) in the
@@ -163,13 +161,11 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
disclosed.
To systematically hide all local variables of a function from error logs,
- do not provide any argument to the ``sensitive_variables`` decorator:
+ do not provide any argument to the ``sensitive_variables`` decorator::
- .. code-block:: python
-
- @sensitive_variables()
- def my_function():
- ...
+ @sensitive_variables()
+ def my_function():
+ ...
.. function:: sensitive_post_parameters(*parameters)
@@ -177,19 +173,17 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
:attr:`POST parameters<HttpRequest.POST>` susceptible to contain sensitive
information, you may prevent the values of those parameters from being
included in the error reports using the ``sensitive_post_parameters``
- decorator:
+ decorator::
- .. code-block:: python
+ from django.views.decorators.debug import sensitive_post_parameters
- from django.views.decorators.debug import sensitive_post_parameters
-
- @sensitive_post_parameters('pass_word', 'credit_card_number')
- def record_user_profile(request):
- UserProfile.create(user=request.user,
- password=request.POST['pass_word'],
- credit_card=request.POST['credit_card_number'],
- name=request.POST['name'])
- ...
+ @sensitive_post_parameters('pass_word', 'credit_card_number')
+ def record_user_profile(request):
+ UserProfile.create(user=request.user,
+ password=request.POST['pass_word'],
+ credit_card=request.POST['credit_card_number'],
+ name=request.POST['name'])
+ ...
In the above example, the values for the ``pass_word`` and
``credit_card_number`` POST parameters will be hidden and replaced with
@@ -197,13 +191,11 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
reports, whereas the value of the ``name`` parameter will be disclosed.
To systematically hide all POST parameters of a request in error reports,
- do not provide any argument to the ``sensitive_post_parameters`` decorator:
-
- .. code-block:: python
+ do not provide any argument to the ``sensitive_post_parameters`` decorator::
- @sensitive_post_parameters()
- def my_view(request):
- ...
+ @sensitive_post_parameters()
+ def my_view(request):
+ ...
.. note::
@@ -231,22 +223,18 @@ decorators' annotations to replace the corresponding values with stars
(`**********`) when the error reports are produced. If you wish to override or
customize this default behavior for your entire site, you need to define your
own filter class and tell Django to use it via the
-:setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` setting:
-
- .. code-block:: python
+:setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` setting::
- DEFAULT_EXCEPTION_REPORTER_FILTER = 'path.to.your.CustomExceptionReporterFilter'
+ DEFAULT_EXCEPTION_REPORTER_FILTER = 'path.to.your.CustomExceptionReporterFilter'
You may also control in a more granular way which filter to use within any
given view by setting the ``HttpRequest``'s ``exception_reporter_filter``
-attribute:
+attribute::
- .. code-block:: python
-
- def my_view(request):
- if request.user.is_authenticated():
- request.exception_reporter_filter = CustomExceptionReporterFilter()
- ...
+ def my_view(request):
+ if request.user.is_authenticated():
+ request.exception_reporter_filter = CustomExceptionReporterFilter()
+ ...
Your custom filter class needs to inherit from
:class:`django.views.debug.SafeExceptionReporterFilter` and may override the
32 docs/howto/i18n.txt
View
@@ -10,16 +10,16 @@ the order in which it examines the different file paths to load the compiled
:term:`message files <message file>` (``.mo``) and the precedence of multiple
translations for the same literal:
- 1. The directories listed in :setting:`LOCALE_PATHS` have the highest
- precedence, with the ones appearing first having higher precedence than
- the ones appearing later.
- 2. Then, it looks for and uses if it exists a ``locale`` directory in each
- of the installed apps listed in :setting:`INSTALLED_APPS`. The ones
- appearing first have higher precedence than the ones appearing later.
- 3. Then, it looks for a ``locale`` directory in the project directory, or
- more accurately, in the directory containing your settings file.
- 4. Finally, the Django-provided base translation in ``django/conf/locale``
- is used as a fallback.
+1. The directories listed in :setting:`LOCALE_PATHS` have the highest
+ precedence, with the ones appearing first having higher precedence than
+ the ones appearing later.
+2. Then, it looks for and uses if it exists a ``locale`` directory in each
+ of the installed apps listed in :setting:`INSTALLED_APPS`. The ones
+ appearing first have higher precedence than the ones appearing later.
+3. Then, it looks for a ``locale`` directory in the project directory, or
+ more accurately, in the directory containing your settings file.
+4. Finally, the Django-provided base translation in ``django/conf/locale``
+ is used as a fallback.
.. deprecated:: 1.3
Lookup in the ``locale`` subdirectory of the directory containing your
@@ -55,12 +55,12 @@ message file specific to the project you are composing. The choice is yours.
All message file repositories are structured the same way. They are:
- * All paths listed in :setting:`LOCALE_PATHS` in your settings file are
- searched for ``<language>/LC_MESSAGES/django.(po|mo)``
- * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` --
- deprecated, see above.
- * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
- * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
+* All paths listed in :setting:`LOCALE_PATHS` in your settings file are
+ searched for ``<language>/LC_MESSAGES/django.(po|mo)``
+* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` --
+ deprecated, see above.
+* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
+* ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
To create message files, you use the :djadmin:`django-admin.py makemessages <makemessages>`
tool. You only need to be in the same directory where the ``locale/`` directory
12 docs/howto/jython.txt
View
@@ -64,10 +64,10 @@ Differences with Django on Jython
At this point, Django on Jython should behave nearly identically to Django
running on standard Python. However, are a few differences to keep in mind:
- * Remember to use the ``jython`` command instead of ``python``. The
- documentation uses ``python`` for consistency, but if you're using Jython
- you'll want to mentally replace ``python`` with ``jython`` every time it
- occurs.
+* Remember to use the ``jython`` command instead of ``python``. The
+ documentation uses ``python`` for consistency, but if you're using Jython
+ you'll want to mentally replace ``python`` with ``jython`` every time it
+ occurs.
- * Similarly, you'll need to use the ``JYTHONPATH`` environment variable
- instead of ``PYTHONPATH``.
+* Similarly, you'll need to use the ``JYTHONPATH`` environment variable
+ instead of ``PYTHONPATH``.
12 docs/howto/legacy-databases.txt
View
@@ -20,12 +20,12 @@ what the name of the database is. Do that by editing the :setting:`DATABASES`
setting and assigning values to the following keys for the ``'default'``
connection:
- * :setting:`NAME`
- * :setting:`ENGINE`
- * :setting:`USER`
- * :setting:`PASSWORD`
- * :setting:`HOST`
- * :setting:`PORT`
+* :setting:`NAME`
+* :setting:`ENGINE`
+* :setting:`USER`
+* :setting:`PASSWORD`
+* :setting:`HOST`
+* :setting:`PORT`
Auto-generate the models
========================
44 docs/howto/outputting-csv.txt
View
@@ -32,27 +32,27 @@ Here's an example::
The code and comments should be self-explanatory, but a few things deserve a
mention:
- * The response gets a special MIME type, :mimetype:`text/csv`. This tells
- browsers that the document is a CSV file, rather than an HTML file. If
- you leave this off, browsers will probably interpret the output as HTML,
- which will result in ugly, scary gobbledygook in the browser window.
+* The response gets a special MIME type, :mimetype:`text/csv`. This tells
+ browsers that the document is a CSV file, rather than an HTML file. If
+ you leave this off, browsers will probably interpret the output as HTML,
+ which will result in ugly, scary gobbledygook in the browser window.
- * The response gets an additional ``Content-Disposition`` header, which
- contains the name of the CSV file. This filename is arbitrary; call it
- whatever you want. It'll be used by browsers in the "Save as..."
- dialogue, etc.
+* The response gets an additional ``Content-Disposition`` header, which
+ contains the name of the CSV file. This filename is arbitrary; call it
+ whatever you want. It'll be used by browsers in the "Save as..."
+ dialogue, etc.
- * Hooking into the CSV-generation API is easy: Just pass ``response`` as the
- first argument to ``csv.writer``. The ``csv.writer`` function expects a
- file-like object, and :class:`~django.http.HttpResponse` objects fit the
- bill.
+* Hooking into the CSV-generation API is easy: Just pass ``response`` as the
+ first argument to ``csv.writer``. The ``csv.writer`` function expects a
+ file-like object, and :class:`~django.http.HttpResponse` objects fit the
+ bill.
- * For each row in your CSV file, call ``writer.writerow``, passing it an
- iterable object such as a list or tuple.
+* For each row in your CSV file, call ``writer.writerow``, passing it an
+ iterable object such as a list or tuple.
- * The CSV module takes care of quoting for you, so you don't have to worry
- about escaping strings with quotes or commas in them. Just pass
- ``writerow()`` your raw strings, and it'll do the right thing.
+* The CSV module takes care of quoting for you, so you don't have to worry
+ about escaping strings with quotes or commas in them. Just pass
+ ``writerow()`` your raw strings, and it'll do the right thing.
Handling Unicode
~~~~~~~~~~~~~~~~
@@ -62,13 +62,13 @@ Unicode internally this means strings read from sources such as
:class:`~django.http.HttpRequest` are potentially problematic. There are a few
options for handling this:
- * Manually encode all Unicode objects to a compatible encoding.
+* Manually encode all Unicode objects to a compatible encoding.
- * Use the ``UnicodeWriter`` class provided in the `csv module's examples
- section`_.
+* Use the ``UnicodeWriter`` class provided in the `csv module's examples
+ section`_.
- * Use the `python-unicodecsv module`_, which aims to be a drop-in
- replacement for :mod:`csv` that gracefully handles Unicode.
+* Use the `python-unicodecsv module`_, which aims to be a drop-in
+ replacement for :mod:`csv` that gracefully handles Unicode.
For more information, see the Python documentation of the :mod:`csv` module.
62 docs/howto/outputting-pdf.txt
View
@@ -63,36 +63,36 @@ Here's a "Hello World" example::
The code and comments should be self-explanatory, but a few things deserve a
mention:
- * The response gets a special MIME type, :mimetype:`application/pdf`. This
- tells browsers that the document is a PDF file, rather than an HTML file.
- If you leave this off, browsers will probably interpret the output as
- HTML, which would result in ugly, scary gobbledygook in the browser
- window.
+* The response gets a special MIME type, :mimetype:`application/pdf`. This
+ tells browsers that the document is a PDF file, rather than an HTML file.
+ If you leave this off, browsers will probably interpret the output as
+ HTML, which would result in ugly, scary gobbledygook in the browser
+ window.
- * The response gets an additional ``Content-Disposition`` header, which
- contains the name of the PDF file. This filename is arbitrary: Call it
- whatever you want. It'll be used by browsers in the "Save as..."
- dialogue, etc.
+* The response gets an additional ``Content-Disposition`` header, which
+ contains the name of the PDF file. This filename is arbitrary: Call it
+ whatever you want. It'll be used by browsers in the "Save as..."
+ dialogue, etc.
- * The ``Content-Disposition`` header starts with ``'attachment; '`` in this
- example. This forces Web browsers to pop-up a dialog box
- prompting/confirming how to handle the document even if a default is set
- on the machine. If you leave off ``'attachment;'``, browsers will handle
- the PDF using whatever program/plugin they've been configured to use for
- PDFs. Here's what that code would look like::
+* The ``Content-Disposition`` header starts with ``'attachment; '`` in this
+ example. This forces Web browsers to pop-up a dialog box
+ prompting/confirming how to handle the document even if a default is set
+ on the machine. If you leave off ``'attachment;'``, browsers will handle
+ the PDF using whatever program/plugin they've been configured to use for
+ PDFs. Here's what that code would look like::
- response['Content-Disposition'] = 'filename=somefilename.pdf'
+ response['Content-Disposition'] = 'filename=somefilename.pdf'
- * Hooking into the ReportLab API is easy: Just pass ``response`` as the
- first argument to ``canvas.Canvas``. The ``Canvas`` class expects a
- file-like object, and :class:`~django.http.HttpResponse` objects fit the
- bill.
+* Hooking into the ReportLab API is easy: Just pass ``response`` as the
+ first argument to ``canvas.Canvas``. The ``Canvas`` class expects a
+ file-like object, and :class:`~django.http.HttpResponse` objects fit the
+ bill.
- * Note that all subsequent PDF-generation methods are called on the PDF
- object (in this case, ``p``) -- not on ``response``.
+* Note that all subsequent PDF-generation methods are called on the PDF
+ object (in this case, ``p``) -- not on ``response``.
- * Finally, it's important to call ``showPage()`` and ``save()`` on the PDF
- file.
+* Finally, it's important to call ``showPage()`` and ``save()`` on the PDF
+ file.
Complex PDFs
============
@@ -137,13 +137,13 @@ Here's the above "Hello World" example rewritten to use :mod:`cStringIO`::
Further resources
=================
- * PDFlib_ is another PDF-generation library that has Python bindings. To
- use it with Django, just use the same concepts explained in this article.
- * `Pisa XHTML2PDF`_ is yet another PDF-generation library. Pisa ships with
- an example of how to integrate Pisa with Django.
- * HTMLdoc_ is a command-line script that can convert HTML to PDF. It
- doesn't have a Python interface, but you can escape out to the shell
- using ``system`` or ``popen`` and retrieve the output in Python.
+* PDFlib_ is another PDF-generation library that has Python bindings. To
+ use it with Django, just use the same concepts explained in this article.
+* `Pisa XHTML2PDF`_ is yet another PDF-generation library. Pisa ships with
+ an example of how to integrate Pisa with Django.
+* HTMLdoc_ is a command-line script that can convert HTML to PDF. It
+ doesn't have a Python interface, but you can escape out to the shell
+ using ``system`` or ``popen`` and retrieve the output in Python.
.. _PDFlib: http://www.pdflib.org/
.. _`Pisa XHTML2PDF`: http://www.xhtml2pdf.com/
62 docs/howto/static-files.txt
View
@@ -345,11 +345,11 @@ Serving the app and your static files from the same server
If you want to serve your static files from the same server that's already
serving your site, the basic outline gets modified to look something like:
- * Push your code up to the deployment server.
- * On the server, run :djadmin:`collectstatic` to copy all the static files
- into :setting:`STATIC_ROOT`.
- * Point your web server at :setting:`STATIC_ROOT`. For example, here's
- :ref:`how to do this under Apache and mod_wsgi <serving-files>`.
+* Push your code up to the deployment server.
+* On the server, run :djadmin:`collectstatic` to copy all the static files
+ into :setting:`STATIC_ROOT`.
+* Point your web server at :setting:`STATIC_ROOT`. For example, here's
+ :ref:`how to do this under Apache and mod_wsgi <serving-files>`.
You'll probably want to automate this process, especially if you've got
multiple web servers. There's any number of ways to do this automation, but
@@ -386,11 +386,11 @@ Most larger Django apps use a separate Web server -- i.e., one that's not also
running Django -- for serving static files. This server often runs a different
type of web server -- faster but less full-featured. Some good choices are:
- * lighttpd_
- * Nginx_
- * TUX_
- * Cherokee_
- * A stripped-down version of Apache_
+* lighttpd_
+* Nginx_
+* TUX_
+* Cherokee_
+* A stripped-down version of Apache_
.. _lighttpd: http://www.lighttpd.net/
.. _Nginx: http://wiki.nginx.org/Main
@@ -404,11 +404,11 @@ server's respective documentation for instructions.
Since your static file server won't be running Django, you'll need to modify
the deployment strategy to look something like:
- * When your static files change, run :djadmin:`collectstatic` locally.
- * Push your local :setting:`STATIC_ROOT` up to the static file server
- into the directory that's being served. ``rsync`` is a good
- choice for this step since it only needs to transfer the
- bits of static files that have changed.
+* When your static files change, run :djadmin:`collectstatic` locally.
+* Push your local :setting:`STATIC_ROOT` up to the static file server
+ into the directory that's being served. ``rsync`` is a good
+ choice for this step since it only needs to transfer the
+ bits of static files that have changed.
Here's how this might look in a fabfile::
@@ -479,27 +479,27 @@ Upgrading from ``django-staticfiles``
you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to
``django.contrib.staticfiles``, you'll need to make a few changes:
- * Application files should now live in a ``static`` directory in each app
- (`django-staticfiles`_ used the name ``media``, which was slightly
- confusing).
+* Application files should now live in a ``static`` directory in each app
+ (`django-staticfiles`_ used the name ``media``, which was slightly
+ confusing).
- * The management commands ``build_static`` and ``resolve_static`` are now
- called :djadmin:`collectstatic` and :djadmin:`findstatic`.
+* The management commands ``build_static`` and ``resolve_static`` are now
+ called :djadmin:`collectstatic` and :djadmin:`findstatic`.
- * The settings ``STATICFILES_PREPEND_LABEL_APPS``,
- ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
- removed.
+* The settings ``STATICFILES_PREPEND_LABEL_APPS``,
+ ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
+ removed.
- * The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
- new :setting:`STATICFILES_FINDERS`.
+* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
+ new :setting:`STATICFILES_FINDERS`.
- * The default for :setting:`STATICFILES_STORAGE` was renamed from
- ``staticfiles.storage.StaticFileStorage`` to
- ``staticfiles.storage.StaticFilesStorage``
+* The default for :setting:`STATICFILES_STORAGE` was renamed from
+ ``staticfiles.storage.StaticFileStorage`` to
+ ``staticfiles.storage.StaticFilesStorage``
- * If using :ref:`runserver<staticfiles-runserver>` for local development
- (and the :setting:`DEBUG` setting is ``True``), you no longer need to add
- anything to your URLconf for serving static files in development.
+* If using :ref:`runserver<staticfiles-runserver>` for local development
+ (and the :setting:`DEBUG` setting is ``True``), you no longer need to add
+ anything to your URLconf for serving static files in development.
Learn more
==========
284 docs/index.txt
View
@@ -34,190 +34,190 @@ Having trouble? We'd like to help!
First steps
===========
- * **From scratch:**
- :doc:`Overview <intro/overview>` |
- :doc:`Installation <intro/install>`
+* **From scratch:**
+ :doc:`Overview <intro/overview>` |
+ :doc:`Installation <intro/install>`
- * **Tutorial:**
- :doc:`Part 1 <intro/tutorial01>` |
- :doc:`Part 2 <intro/tutorial02>` |
- :doc:`Part 3 <intro/tutorial03>` |
- :doc:`Part 4 <intro/tutorial04>`
+* **Tutorial:**
+ :doc:`Part 1 <intro/tutorial01>` |
+ :doc:`Part 2 <intro/tutorial02>` |
+ :doc:`Part 3 <intro/tutorial03>` |
+ :doc:`Part 4 <intro/tutorial04>`
The model layer
===============
- * **Models:**
- :doc:`Model syntax <topics/db/models>` |
- :doc:`Field types <ref/models/fields>` |
- :doc:`Meta options <ref/models/options>`
-
- * **QuerySets:**
- :doc:`Executing queries <topics/db/queries>` |
- :doc:`QuerySet method reference <ref/models/querysets>`
-
- * **Model instances:**
- :doc:`Instance methods <ref/models/instances>` |
- :doc:`Accessing related objects <ref/models/relations>`
-
- * **Advanced:**
- :doc:`Managers <topics/db/managers>` |
- :doc:`Raw SQL <topics/db/sql>` |
- :doc:`Transactions <topics/db/transactions>` |
- :doc:`Aggregation <topics/db/aggregation>` |
- :doc:`Custom fields <howto/custom-model-fields>` |
- :doc:`Multiple databases <topics/db/multi-db>`
-
- * **Other:**
- :doc:`Supported databases <ref/databases>` |
- :doc:`Legacy databases <howto/legacy-databases>` |
- :doc:`Providing initial data <howto/initial-data>` |
- :doc:`Optimize database access <topics/db/optimization>`
+* **Models:**
+ :doc:`Model syntax <topics/db/models>` |
+ :doc:`Field types <ref/models/fields>` |
+ :doc:`Meta options <ref/models/options>`
+
+* **QuerySets:**
+ :doc:`Executing queries <topics/db/queries>` |
+ :doc:`QuerySet method reference <ref/models/querysets>`
+
+* **Model instances:**
+ :doc:`Instance methods <ref/models/instances>` |
+ :doc:`Accessing related objects <ref/models/relations>`
+
+* **Advanced:**
+ :doc:`Managers <topics/db/managers>` |
+ :doc:`Raw SQL <topics/db/sql>` |
+ :doc:`Transactions <topics/db/transactions>` |
+ :doc:`Aggregation <topics/db/aggregation>` |
+ :doc:`Custom fields <howto/custom-model-fields>` |
+ :doc:`Multiple databases <topics/db/multi-db>`
+
+* **Other:**
+ :doc:`Supported databases <ref/databases>` |
+ :doc:`Legacy databases <howto/legacy-databases>` |
+ :doc:`Providing initial data <howto/initial-data>` |
+ :doc:`Optimize database access <topics/db/optimization>`
The template layer
==================
- * **For designers:**
- :doc:`Syntax overview <topics/templates>` |
- :doc:`Built-in tags and filters <ref/templates/builtins>`
+* **For designers:**
+ :doc:`Syntax overview <topics/templates>` |
+ :doc:`Built-in tags and filters <ref/templates/builtins>`
- * **For programmers:**
- :doc:`Template API <ref/templates/api>` |
- :doc:`Custom tags and filters <howto/custom-template-tags>`
+* **For programmers:**
+ :doc:`Template API <ref/templates/api>` |
+ :doc:`Custom tags and filters <howto/custom-template-tags>`
The view layer
==============
- * **The basics:**
- :doc:`URLconfs <topics/http/urls>` |
- :doc:`View functions <topics/http/views>` |
- :doc:`Shortcuts <topics/http/shortcuts>` |
- :doc:`Decorators <topics/http/decorators>`
+* **The basics:**
+ :doc:`URLconfs <topics/http/urls>` |
+ :doc:`View functions <topics/http/views>` |
+ :doc:`Shortcuts <topics/http/shortcuts>` |
+ :doc:`Decorators <topics/http/decorators>`
- * **Reference:**
- :doc:`Request/response objects <ref/request-response>` |
- :doc:`TemplateResponse objects <ref/template-response>`
+* **Reference:**
+ :doc:`Request/response objects <ref/request-response>` |
+ :doc:`TemplateResponse objects <ref/template-response>`
- * **File uploads:**
- :doc:`Overview <topics/http/file-uploads>` |
- :doc:`File objects <ref/files/file>` |
- :doc:`Storage API <ref/files/storage>` |
- :doc:`Managing files <topics/files>` |
- :doc:`Custom storage <howto/custom-file-storage>`
+* **File uploads:**
+ :doc:`Overview <topics/http/file-uploads>` |
+ :doc:`File objects <ref/files/file>` |
+ :doc:`Storage API <ref/files/storage>` |
+ :doc:`Managing files <topics/files>` |
+ :doc:`Custom storage <howto/custom-file-storage>`
- * **Generic views:**
- :doc:`Overview<topics/class-based-views>` |
- :doc:`Built-in generic views<ref/class-based-views>`
+* **Generic views:**
+ :doc:`Overview<topics/class-based-views>` |
+ :doc:`Built-in generic views<ref/class-based-views>`
- * **Advanced:**
- :doc:`Generating CSV <howto/outputting-csv>` |
- :doc:`Generating PDF <howto/outputting-pdf>`
+* **Advanced:**
+ :doc:`Generating CSV <howto/outputting-csv>` |
+ :doc:`Generating PDF <howto/outputting-pdf>`
- * **Middleware:**
- :doc:`Overview <topics/http/middleware>` |
- :doc:`Built-in middleware classes <ref/middleware>`
+* **Middleware:**
+ :doc:`Overview <topics/http/middleware>` |
+ :doc:`Built-in middleware classes <ref/middleware>`
Forms
=====
- * **The basics:**
- :doc:`Overview <topics/forms/index>` |
- :doc:`Form API <ref/forms/api>` |
- :doc:`Built-in fields <ref/forms/fields>` |
- :doc:`Built-in widgets <ref/forms/widgets>`
+* **The basics:**
+ :doc:`Overview <topics/forms/index>` |
+ :doc:`Form API <ref/forms/api>` |
+ :doc:`Built-in fields <ref/forms/fields>` |
+ :doc:`Built-in widgets <ref/forms/widgets>`
- * **Advanced:**
- :doc:`Forms for models <topics/forms/modelforms>` |
- :doc:`Integrating media <topics/forms/media>` |
- :doc:`Formsets <topics/forms/formsets>` |
- :doc:`Customizing validation <ref/forms/validation>`
+* **Advanced:**
+ :doc:`Forms for models <topics/forms/modelforms>` |
+ :doc:`Integrating media <topics/forms/media>` |
+ :doc:`Formsets <topics/forms/formsets>` |
+ :doc:`Customizing validation <ref/forms/validation>`
- * **Extras:**
- :doc:`Form preview <ref/contrib/formtools/form-preview>` |
- :doc:`Form wizard <ref/contrib/formtools/form-wizard>`
+* **Extras:**
+ :doc:`Form preview <ref/contrib/formtools/form-preview>` |
+ :doc:`Form wizard <ref/contrib/formtools/form-wizard>`
The development process
=======================
- * **Settings:**
- :doc:`Overview <topics/settings>` |
- :doc:`Full list of settings <ref/settings>`
+* **Settings:**
+ :doc:`Overview <topics/settings>` |
+ :doc:`Full list of settings <ref/settings>`
- * **Exceptions:**
- :doc:`Overview <ref/exceptions>`
+* **Exceptions:**
+ :doc:`Overview <ref/exceptions>`
- * **django-admin.py and manage.py:**
- :doc:`Overview <ref/django-admin>` |
- :doc:`Adding custom commands <howto/custom-management-commands>`
+* **django-admin.py and manage.py:**
+ :doc:`Overview <ref/django-admin>` |
+ :doc:`Adding custom commands <howto/custom-management-commands>`
- * **Testing:** :doc:`Overview <topics/testing>`
+* **Testing:** :doc:`Overview <topics/testing>`
- * **Deployment:**
- :doc:`Overview <howto/deployment/index>` |
- :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
- :doc:`uWSGI <howto/deployment/uwsgi>` |
- :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` |
- :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
- :doc:`Apache authentication <howto/apache-auth>` |
- :doc:`Handling static files <howto/static-files>` |
- :doc:`Tracking code errors by email <howto/error-reporting>`
+* **Deployment:**
+ :doc:`Overview <howto/deployment/index>` |
+ :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
+ :doc:`uWSGI <howto/deployment/uwsgi>` |
+ :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` |
+ :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
+ :doc:`Apache authentication <howto/apache-auth>` |
+ :doc:`Handling static files <howto/static-files>` |
+ :doc:`Tracking code errors by email <howto/error-reporting>`
Other batteries included
========================
- * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` | :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
- * :doc:`Authentication <topics/auth>`
- * :doc:`Cache system <topics/cache>`
- * :doc:`Clickjacking protection <ref/clickjacking>`
- * :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>`
- * :doc:`Conditional content processing <topics/conditional-view-processing>`
- * :doc:`Content types <ref/contrib/contenttypes>`
- * :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>`
- * :doc:`Cryptographic signing <topics/signing>`
- * :doc:`Databrowse <ref/contrib/databrowse>`
- * :doc:`E-mail (sending) <topics/email>`
- * :doc:`Flatpages <ref/contrib/flatpages>`
- * :doc:`GeoDjango <ref/contrib/gis/index>`
- * :doc:`Humanize <ref/contrib/humanize>`
- * :doc:`Internationalization <topics/i18n/index>`
- * :doc:`Jython support <howto/jython>`
- * :doc:`"Local flavor" <ref/contrib/localflavor>`
- * :doc:`Logging <topics/logging>`
- * :doc:`Messages <ref/contrib/messages>`
- * :doc:`Pagination <topics/pagination>`
- * :doc:`Redirects <ref/contrib/redirects>`
- * :doc:`Security <topics/security>`
- * :doc:`Serialization <topics/serialization>`
- * :doc:`Sessions <topics/http/sessions>`
- * :doc:`Signals <topics/signals>`
- * :doc:`Sitemaps <ref/contrib/sitemaps>`
- * :doc:`Sites <ref/contrib/sites>`
- * :doc:`Static Files <ref/contrib/staticfiles>`
- * :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
- * :doc:`Unicode in Django <ref/unicode>`
- * :doc:`Web design helpers <ref/contrib/webdesign>`
- * :doc:`Validators <ref/validators>`
- * Function-based generic views (Deprecated) :doc:`Overview<topics/generic-views>` | :doc:`Built-in generic views<ref/generic-views>` | :doc:`Migration guide<topics/generic-views-migration>`
+* :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` | :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
+* :doc:`Authentication <topics/auth>`
+* :doc:`Cache system <topics/cache>`
+* :doc:`Clickjacking protection <ref/clickjacking>`
+* :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>`
+* :doc:`Conditional content processing <topics/conditional-view-processing>`
+* :doc:`Content types <ref/contrib/contenttypes>`
+* :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>`
+* :doc:`Cryptographic signing <topics/signing>`
+* :doc:`Databrowse <ref/contrib/databrowse>`
+* :doc:`E-mail (sending) <topics/email>`
+* :doc:`Flatpages <ref/contrib/flatpages>`
+* :doc:`GeoDjango <ref/contrib/gis/index>`
+* :doc:`Humanize <ref/contrib/humanize>`
+* :doc:`Internationalization <topics/i18n/index>`
+* :doc:`Jython support <howto/jython>`
+* :doc:`"Local flavor" <ref/contrib/localflavor>`
+* :doc:`Logging <topics/logging>`
+* :doc:`Messages <ref/contrib/messages>`
+* :doc:`Pagination <topics/pagination>`
+* :doc:`Redirects <ref/contrib/redirects>`
+* :doc:`Security <topics/security>`
+* :doc:`Serialization <topics/serialization>`
+* :doc:`Sessions <topics/http/sessions>`
+* :doc:`Signals <topics/signals>`
+* :doc:`Sitemaps <ref/contrib/sitemaps>`
+* :doc:`Sites <ref/contrib/sites>`
+* :doc:`Static Files <ref/contrib/staticfiles>`
+* :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
+* :doc:`Unicode in Django <ref/unicode>`
+* :doc:`Web design helpers <ref/contrib/webdesign>`
+* :doc:`Validators <ref/validators>`
+* Function-based generic views (Deprecated) :doc:`Overview<topics/generic-views>` | :doc:`Built-in generic views<ref/generic-views>` | :doc:`Migration guide<topics/generic-views-migration>`
The Django open-source project
==============================
- * **Community:**
- :doc:`How to get involved <internals/contributing/index>` |
- :doc:`The release process <internals/release-process>` |
- :doc:`Team of committers <internals/committers>` |
- :doc:`The Django source code repository <internals/svn>`
+* **Community:**
+ :doc:`How to get involved <internals/contributing/index>` |
+ :doc:`The release process <internals/release-process>` |
+ :doc:`Team of committers <internals/committers>` |
+ :doc:`The Django source code repository <internals/svn>`
- * **Design philosophies:**
- :doc:`Overview <misc/design-philosophies>`
+* **Design philosophies:**
+ :doc:`Overview <misc/design-philosophies>`
- * **Documentation:**
- :doc:`About this documentation <internals/contributing/writing-documentation>`
+* **Documentation:**
+ :doc:`About this documentation <internals/contributing/writing-documentation>`
- * **Third-party distributions:**
- :doc:`Overview <misc/distributions>`
+* **Third-party distributions:**
+ :doc:`Overview <misc/distributions>`
- * **Django over time:**
- :doc:`API stability <misc/api-stability>` |
- :doc:`Release notes and upgrading instructions <releases/index>` |
- :doc:`Deprecation Timeline <internals/deprecation>`
+* **Django over time:**
+ :doc:`API stability <misc/api-stability>` |
+ :doc:`Release notes and upgrading instructions <releases/index>` |
+ :doc:`Deprecation Timeline <internals/deprecation>`
154 docs/internals/contributing/bugs-and-features.txt
View
@@ -30,23 +30,23 @@ amount of overhead involved in working with any bug tracking system so your
help in keeping our ticket tracker as useful as possible is appreciated. In
particular:
- * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
- be a well-known question.
+* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
+ be a well-known question.
- * **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
- what you're seeing is a bug.
+* **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
+ what you're seeing is a bug.
- * **Do** write complete, reproducible, specific bug reports. You must
- include a clear, concise description of the problem, and a set of
- instructions for replicating it. Add as much debug information as you can:
- code snippets, test cases, exception backtraces, screenshots, etc. A nice
- small test case is the best way to report a bug, as it gives us an easy
- way to confirm the bug quickly.
+* **Do** write complete, reproducible, specific bug reports. You must
+ include a clear, concise description of the problem, and a set of
+ instructions for replicating it. Add as much debug information as you can:
+ code snippets, test cases, exception backtraces, screenshots, etc. A nice
+ small test case is the best way to report a bug, as it gives us an easy
+ way to confirm the bug quickly.
- * **Don't** post to `django-developers`_ just to announce that you have
- filed a bug report. All the tickets are mailed to another list,
- `django-updates`_, which is tracked by developers and interested
- community members; we see them as they are filed.
+* **Don't** post to `django-developers`_ just to announce that you have
+ filed a bug report. All the tickets are mailed to another list,
+ `django-updates`_, which is tracked by developers and interested
+ community members; we see them as they are filed.
To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`.
@@ -67,27 +67,27 @@ Reporting security issues
In the event of a confirmed vulnerability in Django itself, we will take the
following actions:
- * Acknowledge to the reporter that we've received the report and that a
- fix is forthcoming. We'll give a rough timeline and ask the reporter
- to keep the issue confidential until we announce it.
+* Acknowledge to the reporter that we've received the report and that a
+ fix is forthcoming. We'll give a rough timeline and ask the reporter
+ to keep the issue confidential until we announce it.
- * Focus on developing a fix as quickly as possible and produce patches
- against the current and two previous releases.
+* Focus on developing a fix as quickly as possible and produce patches
+ against the current and two previous releases.
- * Determine a go-public date for announcing the vulnerability and the fix.
- To try to mitigate a possible "arms race" between those applying the
- patch and those trying to exploit the hole, we will not announce
- security problems immediately.
+* Determine a go-public date for announcing the vulnerability and the fix.
+ To try to mitigate a possible "arms race" between those applying the
+ patch and those trying to exploit the hole, we will not announce
+ security problems immediately.
- * Pre-notify third-party distributors of Django ("vendors"). We will send
- these vendor notifications through private email which will include
- documentation of the vulnerability, links to the relevant patch(es), and
- a request to keep the vulnerability confidential until the official
- go-public date.
+* Pre-notify third-party distributors of Django ("vendors"). We will send
+ these vendor notifications through private email which will include
+ documentation of the vulnerability, links to the relevant patch(es), and
+ a request to keep the vulnerability confidential until the official
+ go-public date.
- * Publicly announce the vulnerability and the fix on the pre-determined
- go-public date. This will probably mean a new release of Django, but
- in some cases it may simply be patches against current releases.
+* Publicly announce the vulnerability and the fix on the pre-determined
+ go-public date. This will probably mean a new release of Django, but
+ in some cases it may simply be patches against current releases.
Reporting user interface bugs and features
------------------------------------------
@@ -95,25 +95,25 @@ Reporting user interface bugs and features
If your bug or feature request touches on anything visual in nature, there
are a few additional guidelines to follow:
- * Include screenshots in your ticket which are the visual equivalent of a
- minimal testcase. Show off the issue, not the crazy customizations
- you've made to your browser.
-
- * If the issue is difficult to show off using a still image, consider
- capturing a *brief* screencast. If your software permits it, capture only
- the relevant area of the screen.
-
- * If you're offering a patch which changes the look or behavior of Django's
- UI, you **must** attach before *and* after screenshots/screencasts.
- Tickets lacking these are difficult for triagers and core developers to
- assess quickly.
-
- * Screenshots don't absolve you of other good reporting practices. Make sure
- to include URLs, code snippets, and step-by-step instructions on how to
- reproduce the behavior visible in the screenshots.
-
- * Make sure to set the UI/UX flag on the ticket so interested parties can
- find your ticket.
+* Include screenshots in your ticket which are the visual equivalent of a
+ minimal testcase. Show off the issue, not the crazy customizations
+ you've made to your browser.
+
+* If the issue is difficult to show off using a still image, consider
+ capturing a *brief* screencast. If your software permits it, capture only
+ the relevant area of the screen.
+
+* If you're offering a patch which changes the look or behavior of Django's
+ UI, you **must** attach before *and* after screenshots/screencasts.
+ Tickets lacking these are difficult for triagers and core developers to
+ assess quickly.
+
+* Screenshots don't absolve you of other good reporting practices. Make sure
+ to include URLs, code snippets, and step-by-step instructions on how to
+ reproduce the behavior visible in the screenshots.
+
+* Make sure to set the UI/UX flag on the ticket so interested parties can
+ find your ticket.
Requesting features
-------------------
@@ -121,27 +121,27 @@ Requesting features
We're always trying to make Django better, and your feature requests are a key
part of that. Here are some tips on how to make a request most effectively:
- * Make sure the feature actually requires changes in Django's core. If your
- idea can be developed as an independent application or module — for
- instance, you want to support another database engine — we'll probably
- suggest that you to develop it independently. Then, if your project
- gathers sufficient community support, we may consider it for inclusion in
- Django.
+* Make sure the feature actually requires changes in Django's core. If your
+ idea can be developed as an independent application or module — for
+ instance, you want to support another database engine — we'll probably
+ suggest that you to develop it independently. Then, if your project
+ gathers sufficient community support, we may consider it for inclusion in
+ Django.
- * First request the feature on the `django-developers`_ list, not in the
- ticket tracker. It'll get read more closely if it's on the mailing list.
- This is even more important for large-scale feature requests. We like to
- discuss any big changes to Django's core on the mailing list before
- actually working on them.
+* First request the feature on the `django-developers`_ list, not in the
+ ticket tracker. It'll get read more closely if it's on the mailing list.
+ This is even more important for large-scale feature requests. We like to
+ discuss any big changes to Django's core on the mailing list before
+ actually working on them.
- * Describe clearly and concisely what the missing feature is and how you'd
- like to see it implemented. Include example code (non-functional is OK)
- if possible.
+* Describe clearly and concisely what the missing feature is and how you'd
+ like to see it implemented. Include example code (non-functional is OK)
+ if possible.
- * Explain *why* you'd like the feature. In some cases this is obvious, but
- since Django is designed to help real developers get real work done,
- you'll need to explain it, if it isn't obvious why the feature would be
- useful.
+* Explain *why* you'd like the feature. In some cases this is obvious, but
+ since Django is designed to help real developers get real work done,
+ you'll need to explain it, if it isn't obvious why the feature would be
+ useful.
If core developers agree on the feature, then it's appropriate to create a
ticket. Include a link the discussion on `django-developers`_ in the ticket
@@ -165,14 +165,14 @@ have informal votes on `django-developers`_ about a feature. In these votes we
follow the voting style invented by Apache and used on Python itself, where
votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
- * +1: "I love the idea and I'm strongly committed to it."
+* +1: "I love the idea and I'm strongly committed to it."
- * +0: "Sounds OK to me."
+* +0: "Sounds OK to me."
- * -0: "I'm not thrilled, but I won't stand in the way."
+* -0: "I'm not thrilled, but I won't stand in the way."
- * -1: "I strongly disagree and would be very unhappy to see the idea turn
- into reality."
+* -1: "I strongly disagree and would be very unhappy to see the idea turn
+ into reality."
Although these votes on `django-developers`_ are informal, they'll be taken very
seriously. After a suitable voting period, if an obvious consensus arises we'll
@@ -186,12 +186,12 @@ Any :doc:`core committer</internals/committers>` may call for a formal vote
using the same voting mechanism above. A proposition will be considered carried
by the core team if:
- * There are three "+1" votes from members of the core team.
+* There are three "+1" votes from members of the core team.
- * There is no "-1" vote from any member of the core team.
+* There is no "-1" vote from any member of the core team.
- * The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their
- positive or negative veto.
+* The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their
+ positive or negative veto.
When calling for a vote, the caller should specify a deadline by which
votes must be received. One week is generally suggested as the minimum
124 docs/internals/contributing/committing-code.txt
View
@@ -38,58 +38,58 @@ Committing guidelines
Please follow these guidelines when committing code to Django's Subversion
repository:
- * For any medium-to-big changes, where "medium-to-big" is according to
- your judgment, please bring things up on the `django-developers`_
- mailing list before making the change.
+* For any medium-to-big changes, where "medium-to-big" is according to
+ your judgment, please bring things up on the `django-developers`_
+ mailing list before making the change.
- If you bring something up on `django-developers`_ and nobody responds,
- please don't take that to mean your idea is great and should be
- implemented immediately because nobody contested it. Django's lead
- developers don't have a lot of time to read mailing-list discussions
- immediately, so you may have to wait a couple of days before getting a
- response.
+ If you bring something up on `django-developers`_ and nobody responds,
+ please don't take that to mean your idea is great and should be
+ implemented immediately because nobody contested it. Django's lead
+ developers don't have a lot of time to read mailing-list discussions
+ immediately, so you may have to wait a couple of days before getting a
+ response.
- * Write detailed commit messages in the past tense, not present tense.
+* Write detailed commit messages in the past tense, not present tense.
- * Good: "Fixed Unicode bug in RSS API."
- * Bad: "Fixes Unicode bug in RSS API."
- * Bad: "Fixing Unicode bug in RSS API."
+ * Good: "Fixed Unicode bug in RSS API."
+ * Bad: "Fixes Unicode bug in RSS API."
+ * Bad: "Fixing Unicode bug in RSS API."
- * For commits to a branch, prefix the commit message with the branch name.
- For example: "magic-removal: Added support for mind reading."
+* For commits to a branch, prefix the commit message with the branch name.
+ For example: "magic-removal: Added support for mind reading."
- * Limit commits to the most granular change that makes sense. This means,
- use frequent small commits rather than infrequent large commits. For
- example, if implementing feature X requires a small change to library Y,
- first commit the change to library Y, then commit feature X in a
- separate commit. This goes a *long way* in helping all core Django
- developers follow your changes.
+* Limit commits to the most granular change that makes sense. This means,
+ use frequent small commits rather than infrequent large commits. For
+ example, if implementing feature X requires a small change to library Y,
+ first commit the change to library Y, then commit feature X in a
+ separate commit. This goes a *long way* in helping all core Django
+ developers follow your changes.
- * Separate bug fixes from feature changes.
+* Separate bug fixes from feature changes.
- Bug fixes need to be added to the current bugfix branch as well as the
- current trunk.
+ Bug fixes need to be added to the current bugfix branch as well as the
+ current trunk.
- * If your commit closes a ticket in the Django `ticket tracker`_, begin
- your commit message with the text "Fixed #abc", where "abc" is the
- number of the ticket your commit fixes. Example: "Fixed #123 -- Added
- support for foo". We've rigged Subversion and Trac so that any commit
- message in that format will automatically close the referenced ticket
- and post a comment to it with the full commit message.
+* If your commit closes a ticket in the Django `ticket tracker`_, begin
+ your commit message with the text "Fixed #abc", where "abc" is the
+ number of the ticket your commit fixes. Example: "Fixed #123 -- Added
+ support for foo". We've rigged Subversion and Trac so that any commit
+ message in that format will automatically close the referenced ticket
+ and post a comment to it with the full commit message.
- If your commit closes a ticket and is in a branch, use the branch name
- first, then the "Fixed #abc." For example:
- "magic-removal: Fixed #123 -- Added whizbang feature."
+ If your commit closes a ticket and is in a branch, use the branch name
+ first, then the "Fixed #abc." For example:
+ "magic-removal: Fixed #123 -- Added whizbang feature."
- For the curious: we're using a `Trac post-commit hook`_ for this.
+ For the curious: we're using a `Trac post-commit hook`_ for this.
- .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
+ .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
- * If your commit references a ticket in the Django `ticket tracker`_ but
- does *not* close the ticket, include the phrase "Refs #abc", where "abc"
- is the number of the ticket your commit references. We've rigged
- Subversion and Trac so that any commit message in that format will
- automatically post a comment to the appropriate ticket.
+* If your commit references a ticket in the Django `ticket tracker`_ but
+ does *not* close the ticket, include the phrase "Refs #abc", where "abc"
+ is the number of the ticket your commit references. We've rigged
+ Subversion and Trac so that any commit message in that format will
+ automatically post a comment to the appropriate ticket.
Reverting commits
-----------------
@@ -97,35 +97,35 @@ Reverting commits
Nobody's perfect; mistakes will be committed. When a mistaken commit is
discovered, please follow these guidelines:
- * Try very hard to ensure that mistakes don't happen. Just because we
- have a reversion policy doesn't relax your responsibility to aim for
- the highest quality possible. Really: double-check your work before
- you commit it in the first place!
+* Try very hard to ensure that mistakes don't happen. Just because we
+ have a reversion policy doesn't relax your responsibility to aim for
+ the highest quality possible. Really: double-check your work before
+ you commit it in the first place!
- * If possible, have the original author revert his/her own commit.
+* If possible, have the original author revert his/her own commit.
- * Don't revert another author's changes without permission from the
- original author.
+* Don't revert another author's changes without permission from the
+ original author.
- * If the original author can't be reached (within a reasonable amount
- of time -- a day or so) and the problem is severe -- crashing bug,
- major test failures, etc -- then ask for objections on the
- `django-developers`_ mailing list then revert if there are none.
+* If the original author can't be reached (within a reasonable amount
+ of time -- a day or so) and the problem is severe -- crashing bug,
+ major test failures, etc -- then ask for objections on the
+ `django-developers`_ mailing list then revert if there are none.
- * If the problem is small (a feature commit after feature freeze,
- say), wait it out.
+* If the problem is small (a feature commit after feature freeze,
+ say), wait it out.
- * If there's a disagreement between the committer and the
- reverter-to-be then try to work it out on the `django-developers`_
- mailing list. If an agreement can't be reached then it should
- be put to a vote.
+* If there's a disagreement between the committer and the
+ reverter-to-be then try to work it out on the `django-developers`_
+ mailing list. If an agreement can't be reached then it should
+ be put to a vote.
- * If the commit introduced a confirmed, disclosed security
- vulnerability then the commit may be reverted immediately without
- permission from anyone.
+* If the commit introduced a confirmed, disclosed security
+ vulnerability then the commit may be reverted immediately without
+ permission from anyone.
- * The release branch maintainer may back out commits to the release
- branch without permission if the commit breaks the release branch.
+* The release branch maintainer may back out commits to the release
+ branch without permission if the commit breaks the release branch.
.. _django-developers: http://groups.google.com/group/django-developers
.. _ticket tracker: http://code.djangoproject.com/newticket
48 docs/internals/contributing/index.txt
View
@@ -6,43 +6,43 @@ Django is a community that lives on its volunteers. As it keeps growing, we
always need more people to help others. As soon as you learn Django, you can
contribute in many ways:
- * Join the `django-users`_ mailing list and answer questions. This
- mailing list has a huge audience, and we really want to maintain a
- friendly and helpful atmosphere. If you're new to the Django community,
- you should read the `posting guidelines`_.
+* Join the `django-users`_ mailing list and answer questions. This
+ mailing list has a huge audience, and we really want to maintain a
+ friendly and helpful atmosphere. If you're new to the Django community,
+ you should read the `posting guidelines`_.
- * Join the `#django IRC channel`_ on Freenode and answer questions. By
- explaining Django to other users, you're going to learn a lot about the
- framework yourself.
+* Join the `#django IRC channel`_ on Freenode and answer questions. By
+ explaining Django to other users, you're going to learn a lot about the
+ framework yourself.
- * Blog about Django. We syndicate all the Django blogs we know about on
- the `community page`_; if you'd like to see your blog on that page you
- can `register it here`_.
+* Blog about Django. We syndicate all the Django blogs we know about on
+ the `community page`_; if you'd like to see your blog on that page you
+ can `register it here`_.
- * Contribute to open-source Django projects, write some documentation, or
- release your own code as an open-source pluggable application. The
- ecosystem of pluggable applications is a big strength of Django, help us
- build it!
+* Contribute to open-source Django projects, write some documentation, or
+ release your own code as an open-source pluggable application. The
+ ecosystem of pluggable applications is a big strength of Django, help us
+ build it!
If you think working *with* Django is fun, wait until you start working *on*
it. We're passionate about helping Django users make the jump to contributing
members of the community, so there are several ways you can help Django's
development:
- * :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
+* :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
- * Join the `django-developers`_ mailing list and share your ideas for how
- to improve Django. We're always open to suggestions.
+* Join the `django-developers`_ mailing list and share your ideas for how
+ to improve Django. We're always open to suggestions.
- * :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
- fixed behavior. If you're looking for an easy way to start contributing
- to Django have a look at the `easy pickings`_ tickets.
+* :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
+ fixed behavior. If you're looking for an easy way to start contributing
+ to Django have a look at the `easy pickings`_ tickets.
- * :doc:`Improve the documentation <writing-documentation>` or
- :doc:`write unit tests <writing-code/unit-tests>`.
+* :doc:`Improve the documentation <writing-documentation>` or
+ :doc:`write unit tests <writing-code/unit-tests>`.
- * :doc:`Triage tickets and review patches <triaging-tickets>` created by
- other users.
+* :doc:`Triage tickets and review patches <triaging-tickets>` created by
+ other users.
Really, **ANYONE** can do something to help make Django better and greater!
44 docs/internals/contributing/translations.txt
View
@@ -19,31 +19,31 @@ go to the `translation team`_ page for that language. If you would like to help
out with translating or add a language that isn't yet translated, here's what to
do:
- * Join the `Django i18n mailing list`_ and introduce yourself.
+* Join the `Django i18n mailing list`_ and introduce yourself.
- * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
+* Make sure you read the notes about :ref:`specialties-of-django-i18n`.
- * Signup at `Transifex`_ and visit the `Django project page`_.
+* Signup at `Transifex`_ and visit the `Django project page`_.
- * On the `translation teams`_ page, choose the language team you want
- to work with, **or** -- in case the language team doesn't exist yet --
- request a new team by clicking on the "Request a new team" button
- and select the appropriate language.
+* On the `translation teams`_ page, choose the language team you want
+ to work with, **or** -- in case the language team doesn't exist yet --
+ request a new team by clicking on the "Request a new team" button
+ and select the appropriate language.
- * Then, click the "Join this Team" button to become a member of this team.
- Every team has at least one coordinator who is responsible to review
- your membership request. You can of course also contact the team
- coordinator to clarify procedural problems and handle the actual
- translation process.
+* Then, click the "Join this Team" button to become a member of this team.
+ Every team has at least one coordinator who is responsible to review
+ your membership request. You can of course also contact the team
+ coordinator to clarify procedural problems and handle the actual
+ translation process.
- * Once you are a member of a team choose the translation resource you
- want to update on the team page. For example the "core" resource refers
- to the translation catalogue that contains all non-contrib translations.
- Each of the contrib apps also have a resource (prefixed with "contrib").
+* Once you are a member of a team choose the translation resource you