Fixed #8753: converted "new in ..." callouts to proper Sphinx "versio…

…nadded/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
django · Sep 2, 2008 · 64a9469 · 64a9469
1 parent c435975
commit 64a9469
Show file tree

Hide file tree

Showing 47 changed files with 303 additions and 232 deletions.
diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py
@@ -88,6 +88,34 @@ def visit_desc_parameterlist(self, node):
     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...

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

diff --git 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
@@ -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
+Our policy is:
-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:
 
     **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'
+Our prefered way for marking new features is by prefacing the features'
-documentation with: "New in Django development version." Changes aren't
+documentation with: ".. versionadded:: X.Y", followed by an optional one line
-*required* to include this exact text, but all documentation of new features
+comment and a mandatory blank line.
-should include the phrase "development version," so we can find and remove
+
-those phrases for the next release.
+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
@@ -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
@@ -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
+    * To distinguish feature changes/additions in the docs, we use the phrase:
-      **New in Django development version**. In practice, this means that the
+      "New in version X.Y", being X.Y the next release version (hence, the one
-      current documentation on djangoproject.com can be used by users of either
+      being developed).
-      the latest release *or* the development version.
 
     * 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
@@ -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
@@ -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

diff --git 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
@@ -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
@@ -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
@@ -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

diff --git 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
+      .. versionadded:: 1.0
-      also has a chance to handle the :file:`/rss/beats/` url. In this case,
+         meth:`get_object()` can handle the :file:`/rss/beats/` url.
-      :data:`bits` will be an empty list. In our example, ``len(bits) != 1`` and
+
-      an :exc:`ObjectDoesNotExist` exception will be raised, so
+      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
diff --git 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`
+.. versionadded:: 1.0
-and :setting:`DEFAULT_INDEX_TABLESPACE` settings to specify default values for
+
-the db_tablespace options. These are useful for setting a tablespace for the
+Use the :setting:`DEFAULT_TABLESPACE` and :setting:`DEFAULT_INDEX_TABLESPACE`
-built-in Django apps and other applications whose code you cannot control.
+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
@@ -98,15 +98,16 @@ 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).
 
 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).

diff --git 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::
+.. versionchanged:: 1.0
-    **New in Django development version** The ``cleaned_data`` attribute was
+    The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases.
-    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.