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