diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 61561e7972..560cae7ac7 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -88,6 +88,34 @@ class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator): def depart_desc_parameterlist(self, node): self.body.append(')') pass + + # + # Turn the "new in version" stuff (versoinadded/versionchanged) into a + # better callout -- the Sphinx default is just a little span, + # which is a bit less obvious that I'd like. + # + # FIXME: these messages are all hardcoded in English. We need to chanage + # that to accomodate other language docs, but I can't work out how to make + # that work and I think it'll require Sphinx 0.5 anyway. + # + version_text = { + 'deprecated': 'Deprecated in Django %s', + 'versionchanged': 'Changed in Django %s', + 'versionadded': 'New in Django %s', + } + + def visit_versionmodified(self, node): + self.body.append( + self.starttag(node, 'div', CLASS=node['type']) + ) + title = "%s%s" % ( + self.version_text[node['type']] % node['version'], + len(node) and ":" or "." + ) + self.body.append('%s ' % title) + + def depart_versionmodified(self, node): + self.body.append("\n") # Give each section a unique ID -- nice for custom CSS hooks # This is different on docutils 0.5 vs. 0.4... diff --git a/docs/_static/djangodocs.css b/docs/_static/djangodocs.css index a92aff0cd8..fdaccf70ba 100644 --- a/docs/_static/djangodocs.css +++ b/docs/_static/djangodocs.css @@ -107,6 +107,10 @@ dt .literal, table .literal { background:none; } div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.gif) .8em .8em no-repeat;} div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.gif) .8em .8em no-repeat;} +/*** versoinadded/changes ***/ +div.versionadded, div.versionchanged { } +div.versionadded span.title, div.versionchanged span.title { font-weight: bold; } + /*** p-links ***/ a.headerlink { color: #c60f0f; font-size: 0.8em; padding: 0 4px 0 4px; text-decoration: none; visibility: hidden; } h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, h4:hover > a.headerlink, h5:hover > a.headerlink, h6:hover > a.headerlink, dt:hover > a.headerlink { visibility: visible; } @@ -123,4 +127,4 @@ div#contents ul li { margin-bottom: 0;} div#contents ul ul li { margin-top: 0.3em;} /*** IE hacks ***/ -* pre { width: 100%; } \ No newline at end of file +* pre { width: 100%; } diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index 00f656b92e..b6cc850507 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -3,7 +3,7 @@ Writing custom django-admin commands ==================================== -**New in Django development version** +.. versionadded:: 1.0 Applications can register their own actions with ``manage.py``. For example, you might want to add a ``manage.py`` action for a Django app that you're diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 6b164803d0..93643845ef 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -4,7 +4,7 @@ Writing custom model fields =========================== -**New in Django development version** +.. versionadded:: 1.0 Introduction ============ diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 418a3136ae..e1ddefe02a 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -157,7 +157,7 @@ will use the function's name as the filter name. Filters and auto-escaping ~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 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 @@ -422,7 +422,7 @@ without having to be parsed multiple times. Auto-escaping considerations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 The output from template tags is **not** automatically run through the auto-escaping filters. However, there are still a couple of things you should @@ -547,7 +547,7 @@ current context, available in the ``render`` method:: ``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then format it accordingly. -.. admonition:: New in development version: +.. versionadded:: 1.0 Variable resolution has changed in the development version of Django. ``template.resolve_variable()`` is still available, but has been deprecated diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt index 0303e13153..7612b40020 100644 --- a/docs/howto/deployment/modpython.txt +++ b/docs/howto/deployment/modpython.txt @@ -49,7 +49,10 @@ This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the Django mod_python handler." It passes the value of :ref:`DJANGO_SETTINGS_MODULE ` so mod_python knows which settings to use. -**New in Django development version:** Because mod_python does not know we are +.. versionadded:: 1.0 + The ``PythonOption django.root ...`` is new in this version. + +Because mod_python does not know we are serving this site from underneath the ``/mysite/`` prefix, this value needs to be passed through to the mod_python handler in Django, via the ``PythonOption django.root ...`` line. The value set on that line (the last item) should diff --git a/docs/index.txt b/docs/index.txt index d6a1265c34..24a2f89bd1 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -83,6 +83,7 @@ And more: * :ref:`topics-settings` * :ref:`topics-signals` * :ref:`topics-testing` + * :ref:`topics-http-sessions` Add-on ("contrib") applications =============================== diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index 9cce80e3c9..0e60990542 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -572,28 +572,20 @@ Documentation changes come in two forms: * New features -- Documentation of features that have been added to the framework since the last release. -Our philosophy is that "general improvements" are something that *all* current -Django users should benefit from, including users of trunk *and* users of the -latest release. Hence, the documentation section on djangoproject.com points -people by default to the newest versions of the docs, because they have the -latest and greatest content. (In fact, the Web site pulls directly from the -Subversion repository, converting to HTML on the fly.) - -But this decision to feature bleeding-edge documentation has one large caveat: -any documentation of *new* features will be seen by Django users who don't -necessarily have access to those features yet, because they're only using the -latest release. Thus, our policy is: +Our policy is: **All documentation of new features should be written in a way that clearly designates the features are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.** -Our traditional way of marking new features is by prefacing the features' -documentation with: "New in Django development version." Changes aren't -*required* to include this exact text, but all documentation of new features -should include the phrase "development version," so we can find and remove -those phrases for the next release. +Our prefered way for marking new features is by prefacing the features' +documentation with: ".. versionadded:: X.Y", followed by an optional one line +comment and a mandatory blank line. + +General improvements, or other changes to the APIs that should be emphasised +should use the ".. versionchanged:: X.Y" directive (with the same format as the +``versionadded`` mentioned above. Guidelines for ReST files ------------------------- diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 08ebe1adbb..844812a0db 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -114,9 +114,9 @@ the following output on the command line:: Validating models... 0 errors found. - Django version 0.96, using settings 'mysite.settings' + Django version 1.0, using settings 'mysite.settings' Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows). + Quit the server with CONTROL-C. You've started the Django development server, a lightweight Web server written purely in Python. We've included this with Django so you can develop things diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 012bfe39ee..995e30fdc8 100644 --- a/docs/intro/whatsnext.txt +++ b/docs/intro/whatsnext.txt @@ -216,10 +216,9 @@ We follow this policy: * As we add features to Django's development version, we try to update the documentation in the same Subversion commit transaction. - * To distinguish feature changes/additions in the docs, we use the phrase - **New in Django development version**. In practice, this means that the - current documentation on djangoproject.com can be used by users of either - the latest release *or* the development version. + * To distinguish feature changes/additions in the docs, we use the phrase: + "New in version X.Y", being X.Y the next release version (hence, the one + being developed). * Documentation for a particular Django release is frozen once the version has been released officially. It remains a snapshot of the docs as of the diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 828a4fc0f2..f1c3a1b8f5 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -19,7 +19,7 @@ custom Django application. A flatpage can use a custom template or a default, systemwide flatpage template. It can be associated with one, or multiple, sites. -**New in Django development version** +.. versionadded:: 1.0 The content field may optionally be left blank if you prefer to put your content in a custom template. diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt index fe8d478d40..3923404f93 100644 --- a/docs/ref/contrib/formtools/form-wizard.txt +++ b/docs/ref/contrib/formtools/form-wizard.txt @@ -7,7 +7,7 @@ Form wizard .. module:: django.contrib.formtools.wizard :synopsis: Splits forms across multiple Web pages. -**New in Django development version.** +.. versionadded:: 1.0 Django comes with an optional "form wizard" application that splits :ref:`forms ` across multiple Web pages. It maintains diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt index 4a544f037c..07a62a7fbe 100644 --- a/docs/ref/contrib/humanize.txt +++ b/docs/ref/contrib/humanize.txt @@ -74,7 +74,7 @@ You can pass in either an integer or a string representation of an integer. naturalday ---------- -**New in Django development version** +.. versionadded:: 1.0 For dates that are the current day or within one day, return "today", "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index 2f3075ba04..82a895523c 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -59,7 +59,9 @@ See :ref:`topics-auth`. comments ======== -**New in Django development version.** +.. versionchanged:: 1.0 + The comments application has been rewriten. See :ref:`ref-contrib-comments-upgrade` + for information on howto upgrade. A simple yet flexible comments system. See :ref:`ref-contrib-comments-index`. diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index f8328f2f27..b3f682b687 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -342,7 +342,7 @@ each time you call ``save()``. Pinging Google via `manage.py` ------------------------------ -**New in Django development version** +.. versionadded:: 1.0 Once the sitemaps application is added to your project, you may also ping the Google server's through the command line manage.py interface:: diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 5a29370561..28c8f4d73a 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -230,7 +230,7 @@ To do this, you can use the sites framework. A simple example:: Caching the current ``Site`` object =================================== -**New in Django development version** +.. versionadded:: 1.0 As the current site is stored in the database, each call to ``Site.objects.get_current()`` could result in a database query. But Django is a @@ -379,7 +379,7 @@ Here's how Django uses the sites framework: .. _requestsite-objects: -**New in Django development version** +.. versionadded:: 1.0 Some :ref:`django.contrib ` applications take advantage of the sites framework but are architected in a way that doesn't *require* the diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 9a2e2c02fe..a2ee621cad 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -265,10 +265,13 @@ request to the URL :file:`/rss/beats/0613/`: :exc:`ObjectDoesNotExist` in :meth:`get_object()` tells Django to produce a 404 error for that request. - **New in Django development version:** The :meth:`get_object()` method - also has a chance to handle the :file:`/rss/beats/` url. In this case, - :data:`bits` will be an empty list. In our example, ``len(bits) != 1`` and - an :exc:`ObjectDoesNotExist` exception will be raised, so + .. versionadded:: 1.0 + meth:`get_object()` can handle the :file:`/rss/beats/` url. + + The :meth:`get_object()` method also has a chance to handle the + :file:`/rss/beats/` url. In this case, :data:`bits` will be an + empty list. In our example, ``len(bits) != 1`` and an + :exc:`ObjectDoesNotExist` exception will be raised, so :file:`/rss/beats/` will generate a 404 page. But you can handle this case however you like. For example, you could generate a combined feed for all beats. @@ -476,8 +479,6 @@ This example illustrates all possible attributes and methods for a # for them in this order. This property is only used for Atom feeds # (where it is the feed-level ID element). If not provided, the feed # link is used as the ID. - # - # (New in Django development version) def feed_guid(self, obj): """ @@ -652,8 +653,6 @@ This example illustrates all possible attributes and methods for a # ITEM_GUID -- The following method is optional. This property is # only used for Atom feeds (it is the ID element for an item in an # Atom feed). If not provided, the item's link is used by default. - # - # (New in Django development version) def item_guid(self, obj): """ @@ -989,4 +988,4 @@ For example, you might start implementing an iTunes RSS feed generator like so:: Obviously there's a lot more work to be done for a complete custom feed class, but the above example should demonstrate the basic idea. -.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator \ No newline at end of file +.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 5e1f236de8..66bb836ccc 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -315,10 +315,12 @@ many-to-many table would be stored in the ``indexes`` tablespace. The ``data`` field would also generate an index, but no tablespace for it is specified, so it would be stored in the model tablespace ``tables`` by default. -**New in the Django development version:** Use the :setting:`DEFAULT_TABLESPACE` -and :setting:`DEFAULT_INDEX_TABLESPACE` settings to specify default values for -the db_tablespace options. These are useful for setting a tablespace for the -built-in Django apps and other applications whose code you cannot control. +.. versionadded:: 1.0 + +Use the :setting:`DEFAULT_TABLESPACE` and :setting:`DEFAULT_INDEX_TABLESPACE` +settings to specify default values for the db_tablespace options. +These are useful for setting a tablespace for the built-in Django apps and +other applications whose code you cannot control. Django does not create the tablespaces for you. Please refer to `Oracle's documentation`_ for details on creating and managing tablespaces. diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 26f136b2f7..d53b0d8a55 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -98,7 +98,7 @@ Available subcommands cleanup ------- -**New in Django development version** +.. versionadded:: 1.0 Can be run as a cronjob or directly to clean out old data from the database (only expired sessions at the moment). @@ -106,7 +106,8 @@ Can be run as a cronjob or directly to clean out old data from the database compilemessages --------------- -**New in Django development version** +.. versionchanged:: 1.0 + Before 1.0 this was the "bin/compile-messages.py" command. Compiles .po files created with ``makemessages`` to .mo files for use with the builtin gettext support. See :ref:`topics-i18n`. @@ -134,7 +135,7 @@ createsuperuser .. django-admin:: createsuperuser -**New in Django development version** +.. versionadded:: 1.0 Creates a superuser account (a user who has all permissions). This is useful if you need to create an initial superuser account but did not @@ -209,7 +210,7 @@ objects will be dumped. .. django-admin-option:: --exclude -**New in Django development version** +.. versionadded:: 1.0 Exclude a specific application from the applications whose contents is output. For example, to specifically exclude the `auth` application from @@ -383,7 +384,8 @@ Example usage:: makemessages ------------ -**New in Django development version** +.. versionchanged:: 1.0 + Before 1.0 this was the "bin/make-messages.py" command. Runs over the entire source tree of the current directory and pulls out all strings marked for translation. It creates (or updates) a message file in the @@ -734,7 +736,7 @@ Example usage:: testserver -------------------------------- -**New in Django development version** +.. versionadded:: 1.0 Runs a Django development server (as in ``runserver``) using data from the given fixture(s). diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index f8d8a9940a..72dfcb67c9 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -157,9 +157,8 @@ object:: >>> f.cleaned_data {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} -.. note:: - **New in Django development version** The ``cleaned_data`` attribute was - called ``clean_data`` in earlier releases. +.. versionchanged:: 1.0 + The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases. Note that any text-based field -- such as ``CharField`` or ``EmailField`` -- always cleans the input into a Unicode string. We'll cover the encoding @@ -564,7 +563,7 @@ when printed:: Binding uploaded files to a form -------------------------------- -**New in Django development version** +.. versionadded:: 1.0 Dealing with forms that have ``FileField`` and ``ImageField`` fields is a little more complicated than a normal form. diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 262538fec7..0656c323ae 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -219,9 +219,10 @@ fields. We've specified ``auto_id=False`` to simplify the output:: ``error_messages`` ~~~~~~~~~~~~~~~~~~ +.. versionadded:: 1.0 + .. attribute:: Field.error_messages -**New in Django development version** The ``error_messages`` argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you @@ -314,9 +315,9 @@ For each field, we describe the default widget used if you don't specify the field has ``required=True``. * Error message keys: ``required`` -**New in Django development version:** The empty value for a ``CheckboxInput`` -(and hence the standard ``BooleanField``) has changed to return ``False`` -instead of ``None`` in the development version. +.. versionchanged:: 1.0 + The empty value for a ``CheckboxInput`` (and hence the standard ``BooleanField``) + has changed to return ``False`` instead of ``None`` in the development version. .. note:: @@ -448,15 +449,15 @@ If no ``input_formats`` argument is provided, the default input formats are:: '%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y', # '10/25/06' -**New in Django development version:** The ``DateTimeField`` used to use a -``TextInput`` widget by default. This has now changed. +.. versionchanged:: 1.0 + The ``DateTimeField`` used to use a ``TextInput`` widget by default. This has now changed. ``DecimalField`` ~~~~~~~~~~~~~~~~ -.. class:: DecimalField(**kwargs) +.. versionadded:: 1.0 -**New in Django development version** +.. class:: DecimalField(**kwargs) * Default widget: ``TextInput`` * Empty value: ``None`` @@ -503,9 +504,9 @@ given length. ``FileField`` ~~~~~~~~~~~~~ -.. class:: FileField(**kwargs) +.. versionadded:: 1.0 -**New in Django development version** +.. class:: FileField(**kwargs) * Default widget: ``FileInput`` * Empty value: ``None`` @@ -523,9 +524,9 @@ When you use a ``FileField`` in a form, you must also remember to ``FilePathField`` ~~~~~~~~~~~~~~~~~ -.. class:: FilePathField(**kwargs) +.. versionadded:: 1.0 -**New in Django development version** +.. class:: FilePathField(**kwargs) * Default widget: ``Select`` * Empty value: ``None`` @@ -569,9 +570,9 @@ These control the range of values permitted in the field. ``ImageField`` ~~~~~~~~~~~~~~ -.. class:: ImageField(**kwargs) +.. versionadded:: 1.0 -**New in Django development version** +.. class:: ImageField(**kwargs) * Default widget: ``FileInput`` * Empty value: ``None`` diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index a7d35f4ddd..c9cc292b30 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -38,9 +38,9 @@ commonly used groups of widgets: .. class:: DateTimeInput - Date/time input as a simple text box: ```` + .. versionadded:: 1.0 - **New in Django development version:** + Date/time input as a simple text box: ```` .. class:: Textarea diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt index f92a301c2f..2e4c6d2225 100644 --- a/docs/ref/generic-views.txt +++ b/docs/ref/generic-views.txt @@ -198,9 +198,10 @@ a date in the *future* are not included unless you set ``allow_future`` to specified in ``date_field`` is greater than the current date/time. By default, this is ``False``. - * **New in Django development version:** ``template_object_name``: - Designates the name of the template variable to use in the template - context. By default, this is ``'latest'``. + .. versionadded:: 1.0 + + * ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'latest'``. **Template name:** @@ -223,14 +224,16 @@ In addition to ``extra_context``, the template's context will be: ordered in reverse. This is equivalent to ``queryset.dates(date_field, 'year')[::-1]``. + .. versionchanged:: 1.0 + The behaviour depending on ``template_object_name`` is new in this version. + * ``latest``: The ``num_latest`` objects in the system, ordered descending by ``date_field``. For example, if ``num_latest`` is ``10``, then ``latest`` will be a list of the latest 10 objects in ``queryset``. - **New in Django development version:** This variable's name depends on - the ``template_object_name`` parameter, which is ``'latest'`` by default. - If ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo``. + This variable's name depends on the ``template_object_name`` parameter, + which is ``'latest'`` by default. If ``template_object_name`` is + ``'foo'``, this variable's name will be ``foo``. ``django.views.generic.date_based.archive_year`` ------------------------------------------------ @@ -733,6 +736,9 @@ If ``template_name`` isn't specified, this view will use the template **Template context:** +.. versionadded:: 1.0 + The ``paginator`` and ``page_obj`` context variables are new. + In addition to ``extra_context``, the template's context will be: * ``object_list``: The list of objects. This variable's name depends on the @@ -746,11 +752,9 @@ In addition to ``extra_context``, the template's context will be: If the results are paginated, the context will contain these extra variables: - * **New in Django development version:** ``paginator``: An instance of - ``django.core.paginator.Paginator``. + * ``paginator``: An instance of ``django.core.paginator.Paginator``. - * **New in Django development version:** ``page_obj``: An instance of - ``django.core.paginator.Page``. + * ``page_obj``: An instance of ``django.core.paginator.Page``. Notes on pagination ~~~~~~~~~~~~~~~~~~~ @@ -778,7 +782,7 @@ represented as page ``1``. For more on pagination, read the :ref:`pagination documentation `. -**New in Django development version:** +.. versionadded:: 1.0 As a special case, you are also permitted to use ``last`` as a value for ``page``:: diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 278f00039e..47b4a70927 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -54,9 +54,10 @@ Adds a few conveniences for perfectionists: don't have a valid URL pattern for ``foo.com/bar`` but *do* have a valid pattern for ``foo.com/bar/``. - **New in Django development version:** The behavior of - :setting:`APPEND_SLASH` has changed slightly in the development version. - It didn't used to check whether the pattern was matched in the URLconf. + .. versionchanged:: 1.0 + The behavior of :setting:`APPEND_SLASH` has changed slightly in this + version. It didn't used to check whether the pattern was matched in + the URLconf. If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www." will be redirected to the same URL with a leading "www." @@ -175,7 +176,7 @@ CSRF protection middleware .. class:: django.contrib.csrf.middleware.CsrfMiddleware -**New in Django development version** +.. versionadded:: 1.0 Adds protection against Cross Site Request Forgeries by adding hidden form fields to POST forms and checking requests for the correct value. See the diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index f48d5226b5..370c0284df 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -171,7 +171,7 @@ If ``True``, djadmin:`django-admin.py sqlindexes ` will output a .. attribute:: Field.db_tablespace -**New in Django development version** +.. versionadded:: 1.0 The name of the database tablespace to use for this field's index, if this field is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE` @@ -366,7 +366,7 @@ shortcuts. ``DecimalField`` ---------------- -**New in Django development version** +.. versionadded:: 1.0 .. class:: DecimalField(max_digits=None, decimal_places=None, [**options]) @@ -422,7 +422,7 @@ A file-upload field. Has one **required** argument: date/time of the file upload (so that uploaded files don't fill up the given directory). - **New in Django development version** + .. versionadded:: 1.0 This may also be a callable, such as a function, which will be called to obtain the upload path, including the filename. This callable must be @@ -452,7 +452,7 @@ Also has one optional argument: .. attribute:: FileField.storage - **New in Django development version.** + .. versionadded:: 1.0 Optional. A storage object, which handles the storage and retrieval of your files. See :ref:`topics-files` for details on how to provide this object. @@ -499,7 +499,10 @@ without validation, to a directory that's within your Web server's document root, then somebody could upload a CGI or PHP script and execute that script by visiting its URL on your site. Don't allow that. -**New in development version:** By default, :class:`FileField` instances are +.. versionadded:: 1.0 + The ``max_length`` argument was added in this version. + +By default, :class:`FileField` instances are created as ``varchar(100)`` columns in your database. As with other fields, you can change the maximum length using the :attr:`~CharField.max_length` argument. @@ -542,7 +545,10 @@ base filename, not the full path. So, this example:: because the :attr:`~FilePathField.match` applies to the base filename (``foo.gif`` and ``bar.gif``). -**New in development version:** By default, :class:`FilePathField` instances are +.. versionadded:: 1.0 + The ``max_length`` argument was added in this version. + +By default, :class:`FilePathField` instances are created as ``varchar(100)`` columns in your database. As with other fields, you can change the maximum length using the :attr:`~CharField.max_length` argument. @@ -588,7 +594,10 @@ Requires the `Python Imaging Library`_. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ -**New in development version:** By default, :class:`ImageField` instances are +.. versionadded:: 1.0 + The ``max_length`` argument was added in this version. + +By default, :class:`ImageField` instances are created as ``varchar(100)`` columns in your database. As with other fields, you can change the maximum length using the :attr:`~CharField.max_length` argument. @@ -753,7 +762,10 @@ Note, however, that this only refers to models in the same ``models.py`` file -- you cannot use a string to reference a model defined in another application or imported from elsewhere. -**New in Django development version:** To refer to models defined in another +.. versionchanged:: 1.0 + Refering models in other applications must include the application label. + +To refer to models defined in another application, you must instead explicitly specify the application label. For example, if the ``Manufacturer`` model above is defined in another application called ``production``, you'd need to use:: diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index c315bec89b..06c78c6f62 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -62,7 +62,7 @@ documentation for ``AutoField`` for more details. The ``pk`` property ~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 .. attribute:: Model.pk @@ -172,7 +172,7 @@ auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below. Forcing an INSERT or UPDATE ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 In some rare circumstances, it's necessary to be able to force the ``save()`` method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``. diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index 745e8ceb4f..e4e2d38543 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -55,7 +55,7 @@ Django quotes column and table names behind the scenes. .. attribute:: Options.db_tablespace -**New in Django development version** +.. versionadded:: 1.0 The name of the database tablespace to use for the model. If the backend doesn't support tablespaces, this option is ignored. @@ -152,7 +152,7 @@ It's used in the Django admin and is enforced at the database level (i.e., the appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE`` statement). -**New in Django development version** +.. versionadded:: 1.0 For convenience, unique_together can be a single list when dealing with a single set of fields:: diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 3813ec714f..6da621482a 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -376,7 +376,7 @@ Examples:: ``none()`` ~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to an empty list. This can be used in cases where you know that you should @@ -458,7 +458,8 @@ follow:: p = b.author # Doesn't hit the database. c = p.hometown # Requires a database call. -The ``depth`` argument is new in the Django development version. +.. versionadded:: 1.0 + The ``depth`` argument is new in the Django development version. ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -518,7 +519,8 @@ of the arguments is required, but you should use at least one of them. some database backends, such as some MySQL versions, don't support subqueries. - **New in Django development version** + .. versionadded:: 1.0 + In some rare cases, you might wish to pass parameters to the SQL fragments in ``extra(select=...)```. For this purpose, use the ``select_params`` parameter. Since ``select_params`` is a sequence and the ``select`` @@ -619,10 +621,6 @@ of the arguments is required, but you should use at least one of them. Entry.objects.extra(where=['headline=%s'], params=['Lennon']) -**New in Django development version** The ``select_params`` argument to -``extra()`` is new. Previously, you could attempt to pass parameters for -``select`` in the ``params`` argument, but it worked very unreliably. - QuerySet methods that do not return QuerySets --------------------------------------------- @@ -853,10 +851,11 @@ SQL equivalents:: SELECT ... WHERE id = 14; SELECT ... WHERE id IS NULL; -**New in Django development version:** The semantics of ``id__exact=None`` have -changed in the development version. Previously, it was (intentionally) -converted to ``WHERE id = NULL`` at the SQL level, which would never match -anything. It has now been changed to behave the same as ``id__isnull=True``. +.. versionchanged:: 1.0 + The semantics of ``id__exact=None`` have + changed in the development version. Previously, it was (intentionally) + converted to ``WHERE id = NULL`` at the SQL level, which would never match + anything. It has now been changed to behave the same as ``id__isnull=True``. .. admonition:: MySQL comparisons @@ -1140,7 +1139,7 @@ database to add the full-text index. regex ~~~~~ -**New in Django development version** +.. versionadded:: 1.0 Case-sensitive regular expression match. @@ -1168,7 +1167,7 @@ regular expression syntax is recommended. iregex ~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 Case-insensitive regular expression match. diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 6415a7d335..486ede0a78 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -49,7 +49,7 @@ All attributes except ``session`` should be considered read-only. .. attribute:: HttpRequest.encoding - **New in Django development version** + .. versionadded:: 1.0 A string representing the current encoding used to decode form submission data (or ``None``, which means the ``DEFAULT_CHARSET`` setting is used). @@ -183,7 +183,7 @@ Methods .. method:: HttpRequest.get_host() - **New in Django development version** + .. versionadded:: 1.0 Returns the originating host of the request using information from the ``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If @@ -202,7 +202,7 @@ Methods .. method:: HttpRequest.build_absolute_uri(location) - **New in Django development version** + .. versionadded:: 1.0 Returns the absolute URI form of ``location``. If no location is provided, the location will be set to ``request.get_full_path()``. @@ -220,7 +220,7 @@ Methods .. method:: HttpRequest.is_ajax() - **New in Django development version** + .. versionadded:: 1.0 Returns ``True`` if the request was made via an ``XMLHttpRequest``, by checking the ``HTTP_X_REQUESTED_WITH`` header for the string ``'XMLHttpRequest'``. The @@ -448,13 +448,15 @@ Methods ``status`` is the `HTTP Status code`_ for the response. - **(New in Django development version)** ``content_type`` is an alias for - ``mimetype``. Historically, the parameter was only called ``mimetype``, - but since this is actually the value included in the HTTP ``Content-Type`` - header, it can also include the character set encoding, which makes it - more than just a MIME type specification. If ``mimetype`` is specified - (not ``None``), that value is used. Otherwise, ``content_type`` is used. If - neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is used. + .. versionadded:: 1.0 + + ``content_type`` is an alias for ``mimetype``. Historically, this parameter + was only called ``mimetype``, but since this is actually the value included + in the HTTP ``Content-Type`` header, it can also include the character set + encoding, which makes it more than just a MIME type specification. + If ``mimetype`` is specified (not ``None``), that value is used. + Otherwise, ``content_type`` is used. If neither is given, the + ``DEFAULT_CONTENT_TYPE`` setting is used. .. method:: HttpResponse.__setitem__(header, value) @@ -548,8 +550,9 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in .. class:: HttpResponseBadRequest - **New in Django development version.** Acts just like :class:`HttpResponse` - but uses a 400 status code. + .. versionadded:: 1.0 + + Acts just like :class:`HttpResponse` but uses a 400 status code. .. class:: HttpResponseNotFound diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 6273a3676f..ec62575e71 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -287,7 +287,7 @@ Never deploy a site into production with ``DEBUG`` turned on. DEBUG_PROPAGATE_EXCEPTIONS -------------------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``False`` @@ -342,7 +342,7 @@ site manager(s). DEFAULT_TABLESPACE ------------------ -**New in Django development version** +.. versionadded:: 1.0 Default: ``''`` (Empty string) @@ -354,7 +354,7 @@ backend supports it. DEFAULT_INDEX_TABLESPACE ------------------------ -**New in Django development version** +.. versionadded:: 1.0 Default: ``''`` (Empty string) @@ -435,7 +435,7 @@ trailing space. EMAIL_USE_TLS ------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``False`` @@ -446,7 +446,7 @@ Whether to use a TLS (secure) connection when talking to the SMTP server. FILE_CHARSET ------------ -**New in Django development version** +.. versionadded:: 1.0 Default: ``'utf-8'`` @@ -458,7 +458,7 @@ template files and initial SQL data files. FILE_UPLOAD_HANDLERS -------------------- -**New in Django development version** +.. versionadded:: 1.0 Default:: @@ -472,7 +472,7 @@ A tuple of handlers to use for uploading. See :ref:`topics-files` for details. FILE_UPLOAD_MAX_MEMORY_SIZE --------------------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``2621440`` (i.e. 2.5 MB). @@ -484,7 +484,7 @@ the file system. See :ref:`topics-files` for details. FILE_UPLOAD_TEMP_DIR -------------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``None`` @@ -615,7 +615,7 @@ standard language format. For example, U.S. English is ``"en-us"``. See LANGUAGE_COOKIE_NAME -------------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``'django_language'`` @@ -679,7 +679,7 @@ See :ref:`translations-in-your-own-projects`. LOGIN_REDIRECT_URL ------------------ -**New in Django development version** +.. versionadded:: 1.0 Default: ``'/accounts/profile/'`` @@ -694,7 +694,7 @@ decorator, for example. LOGIN_URL --------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``'/accounts/login/'`` @@ -706,7 +706,7 @@ The URL where requests are redirected for login, specially when using the LOGOUT_URL ---------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``'/accounts/logout/'`` @@ -866,7 +866,7 @@ The e-mail address that error messages come from, such as those sent to SESSION_ENGINE -------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``django.contrib.sessions.backends.db`` @@ -913,7 +913,7 @@ should be different from ``LANGUAGE_COOKIE_NAME``). See the :ref:`topics-http-se SESSION_COOKIE_PATH ------------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``'/'`` @@ -951,7 +951,7 @@ See the :ref:`topics-http-sessions`. SESSION_FILE_PATH ----------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``None`` @@ -1058,7 +1058,7 @@ misspelled) variables. See :ref:`invalid-template-variables`.. TEST_DATABASE_CHARSET --------------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``None`` @@ -1076,7 +1076,7 @@ Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and MySQ TEST_DATABASE_COLLATION ------------------------ -**New in Django development version** +.. versionadded:: 1.0 Default: ``None`` diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index c78f130972..80614ae35c 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -387,7 +387,7 @@ See :ref:`topics-i18n` for more. django.core.context_processors.media ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every ``RequestContext`` will contain a variable ``MEDIA_URL``, providing the diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 2e143a3967..669b97d1e8 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -19,7 +19,7 @@ Built-in tag reference autoescape ~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 Control the current auto-escaping behavior. This tag takes either ``on`` or ``off`` as an argument and that determines whether auto-escaping is in effect @@ -54,8 +54,8 @@ Ignore everything between ``{% comment %}`` and ``{% endcomment %}`` cycle ~~~~~ -**Changed in Django development version** -Cycle among the given strings or variables each time this tag is encountered. +.. versionchanged:: 1.0 + Cycle among the given strings or variables each time this tag is encountered. Within a loop, cycles among the given strings/variables each time through the loop:: @@ -171,7 +171,8 @@ provided in ``athlete_list``:: You can loop over a list in reverse by using ``{% for obj in list reversed %}``. -**New in Django development version** +.. versionadded:: 1.0 + If you need to loop over a list of lists, you can unpack the values in each sub-list into individual variables. For example, if your context contains a list of (x,y) coordinates called ``points``, you could use the @@ -671,9 +672,11 @@ such as this:: The template tag will output the string ``/clients/client/123/``. -**New in development version:** If you're using :ref:`named URL patterns -`, you can refer to the name of the pattern in the ``url`` -tag instead of using the path to the view. +.. versionadded:: 1.0 + +If you're using :ref:`named URL patterns `, you can +refer to the name of the pattern in the ``url`` tag instead of using the +path to the view. Note that if the URL you're reversing doesn't exist, you'll get an :exc:`NoReverseMatch` exception raised, which will cause your site to display an @@ -719,7 +722,7 @@ which is rounded up to 88). with ~~~~ -**New in Django development version** +.. versionadded:: 1.0 Caches a complex variable under a simpler name. This is useful when accessing an "expensive" method (e.g., one that hits the database) multiple times. @@ -758,9 +761,6 @@ addslashes Adds slashes before quotes. Useful for escaping strings in CSV, for example. -**New in Django development version**: For escaping data in JavaScript strings, -use the `escapejs`_ filter instead. - .. templatefilter:: capfirst capfirst @@ -906,16 +906,17 @@ applied to the result will only result in one round of escaping being done. So it is safe to use this function even in auto-escaping environments. If you want multiple escaping passes to be applied, use the ``force_escape`` filter. -**New in Django development version:** Due to auto-escaping, the behavior of -this filter has changed slightly. The replacements are only made once, after -all other filters are applied -- including filters before and after it. +.. versionchanged:: 1.0 + Due to auto-escaping, the behavior of this filter has changed slightly. + The replacements are only made once, after + all other filters are applied -- including filters before and after it. .. templatefilter:: escapejs escapejs ~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 Escapes characters for use in JavaScript strings. This does *not* make the string safe for use in HTML, but does protect you from syntax errors when using @@ -953,6 +954,9 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. fix_ampersands ~~~~~~~~~~~~~~ +.. versionchanged:: 1.0 + This is rarely useful as ampersands are now automatically escaped. See escape_ for more information. + Replaces ampersands with ``&`` entities. For example:: @@ -961,10 +965,6 @@ For example:: If ``value`` is ``Tom & Jerry``, the output will be ``Tom & Jerry``. -**New in Django development version**: This filter generally is no longer -useful, because ampersands are automatically escaped in templates. See escape_ -for more on how auto-escaping works. - .. templatefilter:: floatformat floatformat @@ -1012,7 +1012,7 @@ with an argument of ``-1``. force_escape ~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 Applies HTML escaping to a string (see the ``escape`` filter for details). This filter is applied *immediately* and returns a new, escaped string. This @@ -1067,7 +1067,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string last ~~~~ -**New in Django development version.** +.. versionadded:: 1.0 Returns the last item in a list. @@ -1419,8 +1419,8 @@ unordered_list Recursively takes a self-nested list and returns an HTML unordered list -- WITHOUT opening and closing
    tags. -**New in Django development version:** The format accepted by -``unordered_list`` has changed to be easier to understand. +.. versionchanged:: 1.0 + The format accepted by ``unordered_list`` has changed to be easier to understand. The list is assumed to be in the proper format. For example, if ``var`` contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index 985ab15096..4976a35af9 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -4,7 +4,7 @@ Unicode data in Django ====================== -**New in Django development version** +.. versionadded:: 1.0 Django natively supports Unicode data everywhere. Providing your database can somehow store the data, you can safely pass around Unicode strings to diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index ca73b92ea8..b6e9a9d5dd 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -167,7 +167,8 @@ Methods .. method:: models.User.set_unusable_password() - **New in Django development version.** + .. versionadded:: 1.0 + Marks the user as having no password set. This isn't the same as having a blank string for a password. :meth:`~django.contrib.auth.models.User.check_password()` for this user @@ -179,7 +180,8 @@ Methods .. method:: models.User.has_usable_password() - **New in Django development version.** + .. versionadded:: 1.0 + Returns ``False`` if :meth:`~django.contrib.auth.models.User.set_unusable_password()` has been called for this user. @@ -363,13 +365,14 @@ they're used by Web requests, as explained in the next section. Creating superusers ------------------- +.. versionadded:: 1.0 + The ``manage.py createsuperuser`` command is new. + :djadmin:`manage.py syncdb ` prompts you to create a superuser the first time you run it after adding ``'django.contrib.auth'`` to your :setting:`INSTALLED_APPS`. If you need to create a superuser at a later date, you can use a command line utility. -**New in Django development version.**:: - manage.py createsuperuser --username=joe --email=joe@example.com You will be prompted for a password. After you enter one, the user will be @@ -557,8 +560,10 @@ How to log a user out Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors if the user wasn't logged in. - **New in Django development version:** When you call - :func:`~django.contrib.auth.logout()`, the session + .. versionchanged:: 1.0 + Calling ``logout()`` now cleans session data. + + When you call :func:`~django.contrib.auth.logout()`, the session data for the current request is completely cleaned out. All existing data is removed. This is to prevent another person from using the same web browser to log in and have access to the previous user's session data. diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index f2eb17d930..bc0c407610 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -183,7 +183,7 @@ production environment still will. To activate dummy caching, set Using a custom cache backend ---------------------------- -**New in Django development version** +.. versionadded:: 1.0 While Django includes support for a number of cache backends out-of-the-box, sometimes you will want to use a customised version or your own backend. To @@ -239,9 +239,9 @@ arguments. The per-site cache ================== -**New in Django development version** (previous versions of Django only -provided a single ``CacheMiddleware`` instead of the two pieces described -below). +.. versionchanged:: 1.0 + (previous versions of Django only provided a single ``CacheMiddleware`` instead + of the two pieces described below). Once the cache is set up, the simplest way to use caching is to cache your entire site. You'll need to add @@ -290,7 +290,7 @@ Additionally, the cache middleware automatically sets a few headers in each See :ref:`topics-http-middleware` for more on middleware. -**New in Django development version** +.. versionadded:: 1.0 If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in its ``Cache-Control`` header) then the page will be cached until the expiry @@ -330,7 +330,7 @@ minutes. Template fragment caching ========================= -**New in development version** +.. versionadded:: 1.0 If you're after even more control, you can also cache template fragments using the ``cache`` template tag. To give your template access to this tag, put @@ -408,9 +408,11 @@ get() can take a ``default`` argument:: >>> cache.get('my_key', 'has expired') 'has expired' -**New in Django development version:** To add a key only if it doesn't already -exist, use the ``add()`` method. It takes the same parameters as ``set()``, but -it will not attempt to update the cache if the key specified is already present:: +.. versionadded:: 1.0 + +To add a key only if it doesn't already exist, use the ``add()`` method. +It takes the same parameters as ``set()``, but it will not attempt to +update the cache if the key specified is already present:: >>> cache.set('add_key', 'Initial value') >>> cache.add('add_key', 'New value') diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 8bf1d00a55..b6cc30a224 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -360,7 +360,7 @@ work; all are optional. Extra fields on many-to-many relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 When you're only dealing with simple many-to-many relationships such as mixing and matching pizzas and toppings, a standard :class:`~django.db.models.ManyToManyField` is all you need. However, sometimes @@ -581,7 +581,7 @@ particular database engine. Custom field types ------------------ -**New in Django development version** +.. versionadded:: 1.0 If one of the existing model fields cannot be used to fit your purposes, or if you wish to take advantage of some less common database column types, you can @@ -762,7 +762,7 @@ query. Model inheritance ================= -**New in Django development version** +.. versionadded:: 1.0 Model inheritance in Django works almost identically to the way normal class inheritance works in Python. The only decision you have to make diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 8487a1e0b7..119374c0ed 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -434,7 +434,7 @@ those latter objects, you could write:: Spanning multi-valued relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 When you are filtering an object based on a ``ManyToManyField`` or a reverse ``ForeignKeyField``, there are two different sorts of filter you may be @@ -708,7 +708,7 @@ complete query set:: Updating multiple objects at once ================================= -**New in Django development version** +.. versionadded:: 1.0 Sometimes you want to set a field to a particular value for all the objects in a ``QuerySet``. You can do this with the ``update()`` method. For example:: diff --git a/docs/topics/email.txt b/docs/topics/email.txt index cbc134d2d5..2521385c93 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -181,7 +181,7 @@ from the request's POST data, sends that to admin@example.com and redirects to The EmailMessage and SMTPConnection classes =========================================== -**New in Django development version** +.. versionadded:: 1.0 Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes diff --git a/docs/topics/files.txt b/docs/topics/files.txt index d17af99c48..f4cb67219b 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -4,7 +4,7 @@ Managing files ============== -**New in Django development version** +.. versionadded:: 1.0 This document describes Django's file access APIs. diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 094c57ae5e..1b4650ef26 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -109,9 +109,8 @@ There are three code paths here: 3. If the form has been submitted but is invalid, the bound form instance is passed on to the template. -.. note:: - **New in Django development version** The ``cleaned_data`` attribute was - called ``clean_data`` in earlier releases. +.. versionchanged:: 1.0 + The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases. The distinction between **bound** and **unbound** forms is important. An unbound form does not have any data associated with it; when rendered to the user, it @@ -257,4 +256,4 @@ This covers the basics, but forms can do a whole lot more: .. seealso:: - The :ref:`form API reference `. \ No newline at end of file + The :ref:`form API reference `. diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt index d8bd0dc4f6..24ff0eb205 100644 --- a/docs/topics/http/file-uploads.txt +++ b/docs/topics/http/file-uploads.txt @@ -6,7 +6,7 @@ File Uploads .. currentmodule:: django.core.files -**New in Django development version** +.. versionadded:: 1.0 Most Web sites wouldn't be complete without a way to upload files. When Django handles a file upload, the file data ends up placed in ``request.FILES`` (for diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 35dc67658d..391e9b3e75 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -25,8 +25,9 @@ To enable session functionality, do the following: and run ``manage.py syncdb`` to install the single database table that stores session data. - **New in development version**: this step is optional if you're not using - the database session backend; see `configuring the session engine`_. +.. versionchanged:: 1.0 + This step is optional if you're not using the database session backend; + see `configuring the session engine`_. If you don't want to use sessions, you might as well remove the ``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'`` @@ -35,7 +36,7 @@ from your ``INSTALLED_APPS``. It'll save you a small bit of overhead. Configuring the session engine ============================== -**New in development version**. +.. versionadded:: 1.0. By default, Django stores sessions in your database (using the model ``django.contrib.sessions.models.Session``). Though this is convenient, in @@ -104,15 +105,18 @@ A session object has the following standard dictionary methods: * ``items()`` - * ``setdefault()`` (**New in Django development version**) + * ``setdefault()`` - * ``clear()`` (**New in Django development version**) + * ``clear()`` + +.. versionadded:: 1.0 + ``setdefault()`` and ``clear()`` are new in this version. It also has these methods: * ``flush()`` - **New in Django development version** + .. versionadded:: 1.0 Delete the current session data from the database and regenerate the session key value that is sent back to the user in the cookie. This is @@ -140,7 +144,7 @@ It also has these methods: * ``set_expiry(value)`` - **New in Django development version** + .. versionadded:: 1.0 Sets the expiration time for the session. You can pass a number of different values: @@ -161,7 +165,7 @@ It also has these methods: * ``get_expiry_age()`` - **New in Django development version** + .. versionadded:: 1.0 Returns the number of seconds until this session expires. For sessions with no custom expiration (or those set to expire at browser close), this @@ -169,7 +173,7 @@ It also has these methods: * ``get_expiry_date()`` - **New in Django development version** + .. versionadded:: 1.0 Returns the date this session will expire. For sessions with no custom expiration (or those set to expire at browser close), this will equal the @@ -177,7 +181,7 @@ It also has these methods: * ``get_expire_at_browser_close()`` - **New in Django development version** + .. versionadded:: 1.0 Returns either ``True`` or ``False``, depending on whether the user's session cookie will expire when the user's Web browser is closed. @@ -265,7 +269,7 @@ Here's a typical usage example:: Using sessions out of views =========================== -**New in Django development version** +.. versionadded:: 1.0 An API is available to manipulate session data outside of a view:: @@ -347,7 +351,7 @@ browser-length cookies -- cookies that expire as soon as the user closes his or her browser. Use this if you want people to have to log in every time they open a browser. -**New in Django development version** +.. versionadded:: 1.0 This setting is a global default and can be overwritten at a per-session level by explicitly calling ``request.session.set_expiry()`` as described above in @@ -378,7 +382,7 @@ A few :ref:`Django settings ` give you control over session behavi SESSION_ENGINE -------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``django.contrib.sessions.backends.db`` @@ -393,7 +397,7 @@ See `configuring the session engine`_ for more details. SESSION_FILE_PATH ----------------- -**New in Django development version** +.. versionadded:: 1.0 Default: ``/tmp/`` diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 48d294ff4f..b60ccdd59a 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -42,9 +42,11 @@ Optional arguments context_instance=RequestContext(request)) ``mimetype`` - **New in Django development version:** The MIME type to use for the - resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` - setting. + + .. versionadded:: 1.0 + + The MIME type to use for the resulting document. Defaults to the value of + the :setting:`DEFAULT_CONTENT_TYPE` setting. Example ------- @@ -148,4 +150,4 @@ This example is equivalent to:: def my_view(request): my_objects = MyModel.objects.filter(published=True) if not my_objects: - raise Http404 \ No newline at end of file + raise Http404 diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index c8564a3bb8..db9a348199 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -220,7 +220,7 @@ The remaining arguments should be tuples in this format:: url --- -**New in Django development version** +.. versionadded:: 1.0 You can use the ``url()`` function, instead of a tuple, as an argument to ``patterns()``. This is convenient if you want to specify a name without the @@ -532,7 +532,7 @@ the view prefix (as explained in "The view prefix" above) will have no effect. Naming URL patterns =================== -**New in Django development version** +.. versionadded:: 1.0 It's fairly common to use the same view function in multiple URL patterns in your URLconf. For example, these two URL patterns both point to the ``archive`` diff --git a/docs/topics/pagination.txt b/docs/topics/pagination.txt index 6442341f68..455f62a281 100644 --- a/docs/topics/pagination.txt +++ b/docs/topics/pagination.txt @@ -7,7 +7,8 @@ Pagination .. module:: django.core.paginator :synopsis: Classes to help you easily manage paginated data. -**New in Django development version** +.. versionchanged:: 1.0 + Pagination facilities have been almost fully reworked. Django provides a few classes that help you manage paginated data -- that is, data that's split across several pages, with "Previous/Next" links. These diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index 68ecdffaa4..073964dfac 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -395,7 +395,7 @@ wouldn't know which one of the blocks' content to use. Automatic HTML escaping ======================= -**New in Django development version** +.. versionadded:: 1.0 When generating HTML from templates, there's always a risk that a variable will include characters that affect the resulting HTML. For example, consider this diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt index bc50513611..0916f52388 100644 --- a/docs/topics/testing.txt +++ b/docs/topics/testing.txt @@ -257,7 +257,10 @@ with this command:: Note that we used ``animals``, not ``myproject.animals``. -**New in Django development version:** If you use unit tests, as opposed to +.. versionadded:: 1.0 + You can now choose which test to run. + +If you use unit tests, as opposed to doctests, you can be even *more* specific in choosing which tests to execute. To run a single test case in an application (for example, the ``AnimalTestCase`` described in the "Writing unit tests" section), add the @@ -293,7 +296,9 @@ etc. The test database is created by the user specified by :setting:`DATABASE_USER`, so you'll need to make sure that the given user account has sufficient privileges to create a new database on the system. -**New in Django development version:** For fine-grained control over the +.. versionadded:: 1.0 + +For fine-grained control over the character encoding of your test database, use the :setting:`TEST_DATABASE_CHARSET` setting. If you're using MySQL, you can also use the :setting:`TEST_DATABASE_COLLATION` setting to control the particular @@ -541,7 +546,7 @@ arguments at time of construction: .. method:: Client.login(**credentials) - **New in Django development version** + .. versionadded:: 1.0 If your site uses Django's :ref:`authentication system` and you deal with logging in users, you can use the test client's @@ -581,7 +586,7 @@ arguments at time of construction: .. method:: Client.logout() - **New in Django development version** + .. versionadded:: 1.0 If your site uses Django's :ref:`authentication system`, the ``logout()`` method can be used to simulate the effect of a user @@ -729,7 +734,7 @@ additions. Default test client ~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 .. attribute:: TestCase.client @@ -830,7 +835,7 @@ or by the order of test execution. URLconf configuration ~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 .. attribute:: TestCase.urls @@ -865,7 +870,7 @@ URLconf for the duration of the test case. Emptying the test outbox ~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 If you use Django's custom ``TestCase`` class, the test runner will clear the contents of the test e-mail outbox at the start of each test case. @@ -875,7 +880,7 @@ For more detail on e-mail services during tests, see `E-mail services`_. Assertions ~~~~~~~~~~ -**New in Django development version** +.. versionadded:: 1.0 As Python's normal ``unittest.TestCase`` class implements assertion methods such as ``assertTrue`` and ``assertEquals``, Django's custom ``TestCase`` class @@ -929,7 +934,7 @@ applications: E-mail services --------------- -**New in Django development version** +.. versionadded:: 1.0 If any of your Django views send e-mail using :ref:`Django's e-mail functionality `, you probably don't want to send e-mail each time @@ -1021,7 +1026,7 @@ that can be executed from Python code. Defining a test runner ---------------------- -**New in Django development version** +.. versionadded:: 1.0 .. currentmodule:: django.test.simple @@ -1096,11 +1101,13 @@ provides some utilities that can be useful during testing. * If autoclobber is ``True``, the database will be destroyed without consulting the user. + Returns the name of the test database that it created. + ``create_test_db()`` has the side effect of modifying ``settings.DATABASE_NAME`` to match the name of the test database. - **New in Django development version:** This function returns the name of - the test database that it created. + .. versionchanged:: 1.0 + ``create_test_db()`` now returns the name of the test database. .. function:: destroy_test_db(old_database_name, verbosity=1)