[soc2010/app-loading] merged trunkarchive/soc2010/app-loadingsoc2010/app-loading

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2010/app-loading@13818 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 17 insertions, 12 deletions

diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt
index f8b173cafa..7b25d6bdbe 100644
--- a/docs/howto/custom-management-commands.txt
+++ b/docs/howto/custom-management-commands.txt
@@ -1,5 +1,3 @@
-.. _howto-custom-management-commands:
-
 ====================================
 Writing custom django-admin commands
 ====================================
@@ -8,9 +6,9 @@ Writing custom django-admin commands
 
 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
-distributing. In this document, we will be building a custom ``closepoll`` 
+distributing. In this document, we will be building a custom ``closepoll``
 command for the ``polls`` application from the
-:ref:`tutorial<intro-tutorial01>`.
+:doc:`tutorial</intro/tutorial01>`.
 
 To do this, just add a ``management/commands`` directory to the application.
 Each Python module in that directory will be auto-discovered and registered as
@@ -62,15 +60,22 @@ look like this:
                 poll.opened = False
                 poll.save()
 
-                print 'Successfully closed poll "%s"' % poll_id
+                self.stdout.write('Successfully closed poll "%s"\n' % poll_id)
+
+.. note::
+    When you are using management commands and wish to provide console
+    output, you should write to ``self.stdout`` and ``self.stderr``,
+    instead of printing to ``stdout`` and ``stderr`` directly. By
+    using these proxies, it becomes much easier to test your custom
+    command.
 
-The new custom command can be called using ``python manage.py closepoll 
+The new custom command can be called using ``python manage.py closepoll
 <poll_id>``.
 
 The ``handle()`` method takes zero or more ``poll_ids`` and sets ``poll.opened``
 to ``False`` for each one. If the user referenced any nonexistant polls, a
 :class:`CommandError` is raised. The ``poll.opened`` attribute does not exist
-in the :ref:`tutorial<intro-tutorial01>` and was added to
+in the :doc:`tutorial</intro/tutorial01>` and was added to
 ``polls.models.Poll`` for this example.
 
 The same ``closepoll`` could be easily modified to delete a given poll instead
@@ -91,8 +96,8 @@ must be added to :attr:`~BaseCommand.option_list` like this:
             )
         # ...
 
-In addition to being able to add custom command line options, all 
-:ref:`management commands<ref-django-admin>` can accept some 
+In addition to being able to add custom command line options, all
+:doc:`management commands</ref/django-admin>` can accept some
 default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
 
 Command objects
@@ -113,7 +118,7 @@ Subclassing the :class:`BaseCommand` class requires that you implement the
 Attributes
 ----------
 
-All attributes can be set in your derived class and can be used in 
+All attributes can be set in your derived class and can be used in
 :class:`BaseCommand`'s :ref:`subclasses<ref-basecommand-subclasses>`.
 
 .. attribute:: BaseCommand.args
@@ -133,7 +138,7 @@ All attributes can be set in your derived class and can be used in
 .. attribute:: BaseCommand.help
 
   A short description of the command, which will be printed in the
-  help message when the user runs the command 
+  help message when the user runs the command
   ``python manage.py help <command>``.
 
 .. attribute:: BaseCommand.option_list
@@ -230,7 +235,7 @@ Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement
 A command which takes no arguments on the command line.
 
 Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement
-:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is 
+:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is
 overridden to ensure no arguments are passed to the command.
 
 .. method:: NoArgsCommand.handle_noargs(**options)