Merge branch 'master' into schema-alteration

5 files changed, 56 insertions, 42 deletions

diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt
index 8747375b0a..dd7136c877 100644
--- a/docs/intro/contributing.txt
+++ b/docs/intro/contributing.txt
@@ -389,8 +389,8 @@ This is a new feature, so it should be documented.  Add the following on line
 
     .. versionadded:: 1.5
 
-    The current value of the field will be displayed as a clickable link above the
-    input widget.
+        The current value of the field will be displayed as a clickable link above the
+        input widget.
 
 For more information on writing documentation, including an explanation of what
 the ``versionadded`` bit is all about, see
diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
index 1e0f1da0c5..4247b45238 100644
--- a/docs/intro/reusable-apps.txt
+++ b/docs/intro/reusable-apps.txt
@@ -66,16 +66,17 @@ After the previous tutorials, our project should look like this::
             __init__.py
             admin.py
             models.py
-            tests.py
             static/
-                style.css
-                images/
-                    background.gif
+                polls
+                    images/
+                        background.gif
+                    style.css
             templates/
                 polls/
                     detail.html
                     index.html
                     results.html
+            tests.py
             urls.py
             views.py
         templates/
@@ -129,7 +130,7 @@ this. For a small app like polls, this process isn't too difficult.
 
 2. Move the ``polls`` directory into the ``django-polls`` directory.
 
-3. Create a file ``django-polls/README.txt`` with the following contents::
+3. Create a file ``django-polls/README.rst`` with the following contents::
 
     =====
     Polls
@@ -157,7 +158,7 @@ this. For a small app like polls, this process isn't too difficult.
     3. Run `python manage.py syncdb` to create the polls models.
 
     4. Start the development server and visit http://127.0.0.1:8000/admin/
-      to create a poll (you'll need the Admin app enabled).
+       to create a poll (you'll need the Admin app enabled).
 
     5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
 
@@ -177,23 +178,23 @@ Create a file ``django-polls/setup.py`` with the following contents::
     import os
     from setuptools import setup
 
-    README = open(os.path.join(os.path.dirname(__file__), 'README.txt')).read()
+    README = open(os.path.join(os.path.dirname(__file__), 'README.rst')).read()
 
     # allow setup.py to be run from any path
     os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
 
     setup(
-        name = 'django-polls',
-        version = '0.1',
-        packages = ['polls'],
-        include_package_data = True,
-        license = 'BSD License', # example license
-        description = 'A simple Django app to conduct Web-based polls.',
-        long_description = README,
-        url = 'http://www.example.com/',
-        author = 'Your Name',
-        author_email = 'yourname@example.com',
-        classifiers = [
+        name='django-polls',
+        version='0.1',
+        packages=['polls'],
+        include_package_data=True,
+        license='BSD License',  # example license
+        description='A simple Django app to conduct Web-based polls.',
+        long_description=README,
+        url='http://www.example.com/',
+        author='Your Name',
+        author_email='yourname@example.com',
+        classifiers=[
             'Environment :: Web Environment',
             'Framework :: Django',
             'Intended Audience :: Developers',
@@ -216,10 +217,13 @@ Create a file ``django-polls/setup.py`` with the following contents::
 6. Only Python modules and packages are included in the package by default. To
    include additional files, we'll need to create a ``MANIFEST.in`` file. The
    distribute docs referred to in the previous step discuss this file in more
-   details. To include the templates and our LICENSE file, create a file
-   ``django-polls/MANIFEST.in`` with the following contents::
+   details. To include the templates, the ``README.rst`` and our ``LICENSE``
+   file, create a file ``django-polls/MANIFEST.in`` with the following
+   contents::
 
     include LICENSE
+    include README.rst
+    recursive-include polls/static *
     recursive-include polls/templates *
 
 7. It's optional, but recommended, to include detailed documentation with your
diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt
index 7f69945300..d623bd8451 100644
--- a/docs/intro/tutorial01.txt
+++ b/docs/intro/tutorial01.txt
@@ -23,7 +23,8 @@ If Django is installed, you should see the version of your installation. If it
 isn't, you'll get an error telling "No module named django".
 
 This tutorial is written for Django |version| and Python 2.x. If the Django
-version doesn't match, you can refer to the tutorial for your version of Django
+version doesn't match, you can refer to the tutorial for your version of
+Django by using the version switcher at the bottom right corner of this page,
 or update Django to the newest version. If you are using Python 3.x, be aware
 that your code may need to differ from what is in the tutorial and you should
 continue using the tutorial only if you know what you are doing with Python
@@ -122,7 +123,7 @@ These files are:
   "table of contents" of your Django-powered site. You can read more about
   URLs in :doc:`/topics/http/urls`.
 
-* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible webservers to
+* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible web servers to
   serve your project. See :doc:`/howto/deployment/wsgi/index` for more details.
 
 .. _more about packages: http://docs.python.org/tutorial/modules.html#packages
@@ -242,9 +243,6 @@ come with Django:
 
 * :mod:`django.contrib.sessions` -- A session framework.
 
-* :mod:`django.contrib.sites` -- A framework for managing multiple sites
-  with one Django installation.
-
 * :mod:`django.contrib.messages` -- A messaging framework.
 
 * :mod:`django.contrib.staticfiles` -- A framework for managing
@@ -252,7 +250,7 @@ come with Django:
 
 These applications are included by default as a convenience for the common case.
 
-Each of these applications makes use of at least one database table, though,
+Some of these applications makes use of at least one database table, though,
 so we need to create the tables in the database before we can use them. To do
 that, run the following command:
 
@@ -581,27 +579,32 @@ Wait a minute. ``<Poll: Poll object>`` is, utterly, an unhelpful representation
 of this object. Let's fix that by editing the polls model (in the
 ``polls/models.py`` file) and adding a
 :meth:`~django.db.models.Model.__unicode__` method to both ``Poll`` and
-``Choice``::
+``Choice``. On Python 3, simply replace ``__unicode__`` by ``__str__`` in the
+following example::
 
     class Poll(models.Model):
         # ...
-        def __unicode__(self):
+        def __unicode__(self):  # Python 3: def __str__(self):
             return self.question
 
     class Choice(models.Model):
         # ...
-        def __unicode__(self):
+        def __unicode__(self):  # Python 3: def __str__(self):
             return self.choice_text
 
-It's important to add :meth:`~django.db.models.Model.__unicode__` methods to
-your models, not only for your own sanity when dealing with the interactive
-prompt, but also because objects' representations are used throughout Django's
-automatically-generated admin.
+It's important to add :meth:`~django.db.models.Model.__unicode__` methods (or
+:meth:`~django.db.models.Model.__str__` on Python 3) to your models, not only
+for your own sanity when dealing with the interactive prompt, but also because
+objects' representations are used throughout Django's automatically-generated
+admin.
+
+.. admonition:: `__unicode__` or `__str__`?
 
-.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not
-                :meth:`~django.db.models.Model.__str__`?
+    On Python 3, things are simpler, just use
+    :meth:`~django.db.models.Model.__str__` and forget about
+    :meth:`~django.db.models.Model.__unicode__`.
 
-    If you're familiar with Python, you might be in the habit of adding
+    If you're familiar with Python 2, you might be in the habit of adding
     :meth:`~django.db.models.Model.__str__` methods to your classes, not
     :meth:`~django.db.models.Model.__unicode__` methods. We use
     :meth:`~django.db.models.Model.__unicode__` here because Django models deal
diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt
index 3b0a95f253..97d1d96ad7 100644
--- a/docs/intro/tutorial05.txt
+++ b/docs/intro/tutorial05.txt
@@ -15,9 +15,9 @@ What are automated tests?
 Tests are simple routines that check the operation of your code.
 
 Testing operates at different levels. Some tests might apply to a tiny detail
-- *does a particular model method return values as expected?*, while others
-examine the overall operation of the software - *does a sequence of user inputs
-on the site produce the desired result?* That's no different from the kind of
+(*does a particular model method return values as expected?*) while others
+examine the overall operation of the software (*does a sequence of user inputs
+on the site produce the desired result?*). That's no different from the kind of
 testing you did earlier in :doc:`Tutorial 1 </intro/tutorial01>`, using the
 shell to examine the behavior of a method, or running the application and
 entering data to check how it behaves.
@@ -326,6 +326,13 @@ in the shell::
     >>> from django.test.utils import setup_test_environment
     >>> setup_test_environment()
 
+:meth:`~django.test.utils.setup_test_environment` installs a template renderer
+which will allow us to examine some additional attributes on responses such as
+``response.context`` that otherwise wouldn't be available. Note that this
+method *does not* setup a test database, so the following will be run against
+the existing database and the output may differ slightly depending on what
+polls you already created.
+
 Next we need to import the test client class (later in ``tests.py`` we will use
 the :class:`django.test.TestCase` class, which comes with its own client, so
 this won't be required)::
diff --git a/docs/intro/tutorial06.txt b/docs/intro/tutorial06.txt
index 6b3d0f35e2..d5db3ae232 100644
--- a/docs/intro/tutorial06.txt
+++ b/docs/intro/tutorial06.txt
@@ -108,7 +108,7 @@ loaded in the bottom right of the screen.
 
 These are the **basics**. For more details on settings and other bits included
 with the framework see
-:doc:`the static files howto </howto/static-files/index>` and the
+:doc:`the static files howto </howto/static-files/index>` and
 :doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying
 static files </howto/static-files/deployment>` discusses how to use static
 files on a real server.