Fixed #8753: converted "new in ..." callouts to proper Sphinx "versionadded/versionchanged" directives. Thanks to Marc Fargas for all the heavy lifting here.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8843 bcc190cf-cafb-0310-a4f2-bffc1f526a37

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('<span class="title">%s</span> ' % title)
+    
+    def depart_versionmodified(self, node):
+        self.body.append("</div>\n")
     
     # Give each section a unique ID -- nice for custom CSS hooks
     # This is different on docutils 0.5 vs. 0.4...

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%; }
+* pre { width: 100%; }

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

docs/howto/custom-model-fields.txt

@@ -4,7 +4,7 @@
 Writing custom model fields
 ===========================
 
-**New in Django development version**
+.. versionadded:: 1.0
 
 Introduction
 ============

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

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
 <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

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
 ===============================

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
 -------------------------

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

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

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.

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 <topics-forms-index>` across multiple Web pages. It maintains

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

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`.
 

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::

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 <ref-contrib-index>` applications take advantage of
 the sites framework but are architected in a way that doesn't *require* the

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
+.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator

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.

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 <fixture fixture ...>
 --------------------------------
 
-**New in Django development version**
+.. versionadded:: 1.0
 
 Runs a Django development server (as in ``runserver``) using data from the
 given fixture(s).

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.

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``

docs/ref/forms/widgets.txt

@@ -38,9 +38,9 @@ commonly used groups of widgets:
 
 .. class:: DateTimeInput
 
-    Date/time input as a simple text box: ``<input type='text' ...>``
+    .. versionadded:: 1.0
 
-    **New in Django development version:**
+    Date/time input as a simple text box: ``<input type='text' ...>``
 
 .. class:: Textarea
 

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
 <topics-pagination>`.
 
-**New in Django development version:** 
+.. versionadded:: 1.0
 
 As a special case, you are also permitted to use ``last`` as a value for
 ``page``::

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

docs/ref/models/fields.txt

@@ -171,7 +171,7 @@ If ``True``, djadmin:`django-admin.py sqlindexes <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::

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``.

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::

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.
 

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
 

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``
 

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

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
-<naming-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 <naming-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 ``&amp;`` entities.
 
 For example::
@@ -961,10 +965,6 @@ For example::
 
 If ``value`` is ``Tom & Jerry``, the output will be ``Tom &amp; 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 <ul> 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

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

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 <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.

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')

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

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::

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

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.
 

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 <ref-forms-index>`.
+    The :ref:`form API reference <ref-forms-index>`.

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

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 <ref-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/``
 

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
+            raise Http404

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``

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

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

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<topics-auth>`
         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<topics-auth>`,
         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 <topics-email>`, 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)