Permalink
Browse files

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
  • Loading branch information...
1 parent c435975 commit 64a94691277db17e87614f125d8da78a9995076b @jacobian jacobian committed Sep 2, 2008
Showing with 303 additions and 232 deletions.
  1. +28 −0 docs/_ext/djangodocs.py
  2. +5 −1 docs/_static/djangodocs.css
  3. +1 −1 docs/howto/custom-management-commands.txt
  4. +1 −1 docs/howto/custom-model-fields.txt
  5. +3 −3 docs/howto/custom-template-tags.txt
  6. +4 −1 docs/howto/deployment/modpython.txt
  7. +1 −0 docs/index.txt
  8. +8 −16 docs/internals/contributing.txt
  9. +2 −2 docs/intro/tutorial01.txt
  10. +3 −4 docs/intro/whatsnext.txt
  11. +1 −1 docs/ref/contrib/flatpages.txt
  12. +1 −1 docs/ref/contrib/formtools/form-wizard.txt
  13. +1 −1 docs/ref/contrib/humanize.txt
  14. +3 −1 docs/ref/contrib/index.txt
  15. +1 −1 docs/ref/contrib/sitemaps.txt
  16. +2 −2 docs/ref/contrib/sites.txt
  17. +8 −9 docs/ref/contrib/syndication.txt
  18. +6 −4 docs/ref/databases.txt
  19. +8 −6 docs/ref/django-admin.txt
  20. +3 −4 docs/ref/forms/api.txt
  21. +15 −14 docs/ref/forms/fields.txt
  22. +2 −2 docs/ref/forms/widgets.txt
  23. +16 −12 docs/ref/generic-views.txt
  24. +5 −4 docs/ref/middleware.txt
  25. +20 −8 docs/ref/models/fields.txt
  26. +2 −2 docs/ref/models/instances.txt
  27. +2 −2 docs/ref/models/options.txt
  28. +12 −13 docs/ref/models/querysets.txt
  29. +16 −13 docs/ref/request-response.txt
  30. +17 −17 docs/ref/settings.txt
  31. +1 −1 docs/ref/templates/api.txt
  32. +23 −23 docs/ref/templates/builtins.txt
  33. +1 −1 docs/ref/unicode.txt
  34. +11 −6 docs/topics/auth.txt
  35. +11 −9 docs/topics/cache.txt
  36. +3 −3 docs/topics/db/models.txt
  37. +2 −2 docs/topics/db/queries.txt
  38. +1 −1 docs/topics/email.txt
  39. +1 −1 docs/topics/files.txt
  40. +3 −4 docs/topics/forms/index.txt
  41. +1 −1 docs/topics/http/file-uploads.txt
  42. +18 −14 docs/topics/http/sessions.txt
  43. +6 −4 docs/topics/http/shortcuts.txt
  44. +2 −2 docs/topics/http/urls.txt
  45. +2 −1 docs/topics/pagination.txt
  46. +1 −1 docs/topics/templates.txt
  47. +19 −12 docs/topics/testing.txt
@@ -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...
@@ -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%; }
@@ -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
@@ -4,7 +4,7 @@
Writing custom model fields
===========================
-**New in Django development version**
+.. versionadded:: 1.0
Introduction
============
@@ -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
@@ -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
View
@@ -83,6 +83,7 @@ And more:
* :ref:`topics-settings`
* :ref:`topics-signals`
* :ref:`topics-testing`
+ * :ref:`topics-http-sessions`
Add-on ("contrib") applications
===============================
@@ -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
-------------------------
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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`.
@@ -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::
@@ -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
@@ -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
@@ -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.
@@ -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).
@@ -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.
Oops, something went wrong. Retry.

0 comments on commit 64a9469

Please sign in to comment.