Fixed #5369 -- Refactored the django-admin.py help system, allowing each subcommand to register its own options. Thanks for the patch, Todd O'Bryan

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6075 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/core/management/__init__.py

@@ -52,76 +52,59 @@ class ManagementUtility(object):
         names = [f[:-3] for f in os.listdir(command_dir) if not f.startswith('_') and f.endswith('.py')]
         return dict([(name, load_command_class(name)) for name in names])
 
-    def usage(self):
+    def print_help(self, argv):
         """
-        Returns a usage string, for use with optparse.
+        Returns the help message, as a string.
-
-        The string doesn't include the options (e.g., "--verbose"), because
-        optparse puts those in automatically.
         """
-        usage = ["%prog command [options]\nactions:"]
+        prog_name = os.path.basename(argv[0])
-        commands = self.commands.items()
+        usage = ['%s <subcommand> [options] [args]' % prog_name]
+        usage.append('Django command line tool, version %s' % django.get_version())
+        usage.append("Type '%s help <subcommand>' for help on a specific subcommand." % prog_name)
+        usage.append('Available subcommands:')
+        commands = self.commands.keys()
         commands.sort()
-        for name, cmd in commands:
+        for cmd in commands:
-            usage.append('  %s %s' % (name, cmd.args))
+            usage.append('  %s' % cmd)
-            usage.extend(textwrap.wrap(cmd.help, initial_indent='    ', subsequent_indent='    '))
+        print '\n'.join(usage)
-            usage.append('')
+
-        return '\n'.join(usage[:-1]) # Cut off the last list element, an empty space.
+    def fetch_command(self, subcommand, command_name):
+        """
+        Tries to fetch the given subcommand, printing a message with the
+        appropriate command called from the command line (usually
+        django-admin.py or manage.py) if it can't be found.
+        """
+        try:
+            return self.commands[subcommand]
+        except KeyError:
+            sys.stderr.write("Unknown command: %r\nType '%s help' for usage.\n" % (subcommand, command_name))
+            sys.exit(1)
 
     def execute(self, argv=None):
         """
-        Parses the given argv from the command line, determines which command
+        Figures out which command is being run (the first arg), creates a parser
-        to run and runs the command.
+        appropriate to that command, and runs it.
         """
         if argv is None:
             argv = sys.argv
-
-        # Create the parser object and parse the command-line args.
-        # TODO: Ideally each Command class would register its own options for
-        # add_option(), but we'd need to figure out how to allow for multiple
-        # Commands using the same options. The optparse library gets in the way
-        # by checking for conflicts:
-        # http://docs.python.org/lib/optparse-conflicts-between-options.html
-        parser = OptionParser(usage=self.usage(), version=get_version())
-        parser.add_option('--settings',
-            help='The Python path to a settings module, e.g. "myproject.settings.main". If this isn\'t provided, the DJANGO_SETTINGS_MODULE environment variable will be used.')
-        parser.add_option('--pythonpath',
-            help='A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".')
-        parser.add_option('--plain', action='store_true', dest='plain',
-            help='When using "shell": Tells Django to use plain Python, not IPython.')
-        parser.add_option('--noinput', action='store_false', dest='interactive', default=True,
-            help='Tells Django to NOT prompt the user for input of any kind.')
-        parser.add_option('--noreload', action='store_false', dest='use_reloader', default=True,
-            help='When using "runserver": Tells Django to NOT use the auto-reloader.')
-        parser.add_option('--format', default='json', dest='format',
-            help='Specifies the output serialization format for fixtures')
-        parser.add_option('--indent', default=None, dest='indent',
-            type='int', help='Specifies the indent level to use when pretty-printing output')
-        parser.add_option('--verbosity', action='store', dest='verbosity', default='1',
-            type='choice', choices=['0', '1', '2'],
-            help='Verbosity level; 0=minimal output, 1=normal output, 2=all output')
-        parser.add_option('--adminmedia', dest='admin_media_path', default='',
-            help='When using "runserver": Specifies the directory from which to serve admin media.')
-        options, args = parser.parse_args(argv[1:])
-
-        # If the 'settings' or 'pythonpath' options were submitted, activate those.
-        if options.settings:
-            os.environ['DJANGO_SETTINGS_MODULE'] = options.settings
-        if options.pythonpath:
-            sys.path.insert(0, options.pythonpath)
-
-        # Run the appropriate command.
         try:
-            command_name = args[0]
+            command_name = argv[1]
         except IndexError:
-            sys.stderr.write("Type '%s --help' for usage.\n" % os.path.basename(argv[0]))
+            sys.stderr.write("Type '%s help' for usage.\n" % os.path.basename(argv[0]))
             sys.exit(1)
-        try:
+
-            command = self.commands[command_name]
+        if command_name == 'help':
-        except KeyError:
+            if len(argv) > 2:
-            sys.stderr.write("Unknown command: %r\nType '%s --help' for usage.\n" % (command_name, os.path.basename(argv[0])))
+                self.fetch_command(argv[2], argv[0]).print_help(argv[2:])
-            sys.exit(1)
+            else:
-        command.execute(*args[1:], **options.__dict__)
+                self.print_help(argv)
+        # Special-cases: We want 'django-admin.py --version' and
+        # 'django-admin.py --help' to work, for backwards compatibility.
+        elif argv[1:] == ['--version']:
+            print django.get_version()
+        elif argv[1:] == ['--help']:
+            self.print_help(argv)
+        else:
+            self.fetch_command(command_name, argv[0]).run(argv[1:])
 
 class ProjectManagementUtility(ManagementUtility):
     """

django/core/management/base.py

@@ -1,13 +1,23 @@
+import django
 from django.core.exceptions import ImproperlyConfigured
 from django.core.management.color import color_style
+import itertools
+from optparse import make_option, OptionParser
 import sys
 import os
+from traceback import print_exc
 
 class CommandError(Exception):
     pass
 
 class BaseCommand(object):
     # Metadata about this command.
+    option_list = (
+        make_option('--settings',
+            help='The Python path to a settings module, e.g. "myproject.settings.main". If this isn\'t provided, the DJANGO_SETTINGS_MODULE environment variable will be used.'),
+        make_option('--pythonpath',
+            help='A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".'),
+    )
     help = ''
     args = ''
 
@@ -19,6 +29,43 @@ class BaseCommand(object):
     def __init__(self):
         self.style = color_style()
 
+    def get_version(self):
+        """
+        Returns the Django version, which should be correct for all built-in
+        Django commands. User-supplied commands should override this method.
+        """
+        return django.get_version()
+
+    def usage(self):
+        usage = '%prog [options] ' + self.args
+        if self.help:
+            return '%s\n\n%s' % (usage, self.help)
+        else:
+            return usage
+
+    def create_parser(self, prog_name):
+        return OptionParser(prog=prog_name,
+                            usage=self.usage(),
+                            version=self.get_version(),
+                            option_list=self.option_list)
+
+    def print_help(self, args):
+        parser = self.create_parser(args[0])
+        parser.print_help()
+
+    def run(self, args):
+        parser = self.create_parser(args[0])
+        (options, args) = parser.parse_args(args[1:])
+        if options.settings:
+            os.environ['DJANGO_SETTINGS_MODULE'] = options.settings
+        if options.pythonpath:
+            sys.path.insert(0, options.pythonpath)
+        try:
+            self.execute(*args, **options.__dict__)
+        except Exception, e:
+            print_exc()
+            parser.print_usage()
+
     def execute(self, *args, **options):
         # Switch to English, because django-admin.py creates database content
         # like permissions, and those shouldn't contain any translations.
@@ -69,7 +116,7 @@ class BaseCommand(object):
         raise NotImplementedError()
 
 class AppCommand(BaseCommand):
-    args = '[appname ...]'
+    args = '<appname appname ...>'
 
     def handle(self, *app_labels, **options):
         from django.db import models
@@ -90,7 +137,7 @@ class AppCommand(BaseCommand):
         raise NotImplementedError()
 
 class LabelCommand(BaseCommand):
-    args = '[label ...]'
+    args = '<label label ...>'
     label = 'label'
 
     def handle(self, *labels, **options):
@@ -168,4 +215,3 @@ def _make_writeable(filename):
       st = os.stat(filename)
       new_permissions = stat.S_IMODE(st.st_mode) | stat.S_IWUSR
       os.chmod(filename, new_permissions)
-

django/core/management/commands/createcachetable.py

@@ -2,7 +2,7 @@ from django.core.management.base import LabelCommand
 
 class Command(LabelCommand):
     help = "Creates the table needed to use the SQL cache backend."
-    args = "[tablename]"
+    args = "<tablename>"
     label = 'tablename'
 
     requires_model_validation = False

django/core/management/commands/dumpdata.py

@@ -1,8 +1,16 @@
 from django.core.management.base import BaseCommand, CommandError
 
+from optparse import make_option
+
 class Command(BaseCommand):
+    option_list = (
+        make_option('--format', default='json', dest='format',
+            help='Specifies the output serialization format for fixtures'),
+        make_option('--indent', default=None, dest='indent', type='int',
+            help='Specifies the indent level to use when pretty-printing output'),
+    )
     help = 'Output the contents of the database as a fixture of the given format.'
-    args = '[--format] [--indent] [appname ...]'
+    args = '[appname ...]'
 
     def handle(self, *app_labels, **options):
         from django.db.models import get_app, get_apps, get_models

django/core/management/commands/flush.py

@@ -1,9 +1,16 @@
 from django.core.management.base import NoArgsCommand, CommandError
 from django.core.management.color import no_style
+from optparse import make_option
 
 class Command(NoArgsCommand):
+    option_list = NoArgsCommand.option_list + (
+        make_option('--verbosity', action='store', dest='verbosity', default='1',
+            type='choice', choices=['0', '1', '2'],
+            help='Verbosity level; 0=minimal output, 1=normal output, 2=all output'),
+        make_option('--noinput', action='store_false', dest='interactive', default=True,
+            help='Tells Django to NOT prompt the user for input of any kind.'),
+    )
     help = "Executes ``sqlflush`` on the current database."
-    args = '[--verbosity] [--noinput]'
 
     def handle_noargs(self, **options):
         from django.conf import settings

django/core/management/commands/loaddata.py

@@ -1,5 +1,6 @@
 from django.core.management.base import BaseCommand
 from django.core.management.color import no_style
+from optparse import make_option
 import sys
 import os
 
@@ -9,8 +10,13 @@ except NameError:
     from sets import Set as set   # Python 2.3 fallback
 
 class Command(BaseCommand):
+    option_list = BaseCommand.option_list + (
+        make_option('--verbosity', action='store', dest='verbosity', default='1',
+            type='choice', choices=['0', '1', '2'],
+            help='Verbosity level; 0=minimal output, 1=normal output, 2=all output'),
+    )
     help = 'Installs the named fixture(s) in the database.'
-    args = "[--verbosity] fixture, fixture, ..."
+    args = "fixture [fixture ...]"
 
     def handle(self, *fixture_labels, **options):
         from django.db.models import get_apps

django/core/management/commands/reset.py

@@ -1,9 +1,14 @@
 from django.core.management.base import AppCommand, CommandError
 from django.core.management.color import no_style
+from optparse import make_option
 
 class Command(AppCommand):
+    option_list = AppCommand.option_list + (
+        make_option('--noinput', action='store_false', dest='interactive', default=True,
+            help='Tells Django to NOT prompt the user for input of any kind.'),
+    )
     help = "Executes ``sqlreset`` for the given app(s) in the current database."
-    args = '[--noinput] [appname ...]'
+    args = '[appname ...]'
 
     output_transaction = True
 

django/core/management/commands/runfcgi.py

@@ -14,3 +14,7 @@ class Command(BaseCommand):
             pass
         from django.core.servers.fastcgi import runfastcgi
         runfastcgi(args)
+        
+    def usage(self):
+        from django.core.servers.fastcgi import FASTCGI_HELP
+        return FASTCGI_HELP

django/core/management/commands/runserver.py

@@ -1,10 +1,17 @@
 from django.core.management.base import BaseCommand, CommandError
+from optparse import make_option
 import os
 import sys
 
 class Command(BaseCommand):
+    option_list = BaseCommand.option_list + (
+        make_option('--noreload', action='store_false', dest='use_reloader', default=True,
+            help='Tells Django to NOT use the auto-reloader.'),
+        make_option('--adminmedia', dest='admin_media_path', default='',
+            help='Specifies the directory from which to serve admin media.'),
+    )
     help = "Starts a lightweight Web server for development."
-    args = '[--noreload] [--adminmedia=ADMIN_MEDIA_PATH] [optional port number, or ipaddr:port]'
+    args = '[optional port number, or ipaddr:port]'
 
     # Validation is called explicitly each time the server is reloaded.
     requires_model_validation = False

django/core/management/commands/shell.py

@@ -1,8 +1,12 @@
 from django.core.management.base import NoArgsCommand
+from optparse import make_option
 
 class Command(NoArgsCommand):
+    option_list = NoArgsCommand.option_list + (
+        make_option('--plain', action='store_true', dest='plain',
+            help='Tells Django to use plain Python, not IPython.'),
+    )
     help = "Runs a Python interactive interpreter. Tries to use IPython, if it's available."
-    args = '[--plain]'
 
     requires_model_validation = False
 

django/core/management/commands/syncdb.py

@@ -1,5 +1,6 @@
 from django.core.management.base import NoArgsCommand
 from django.core.management.color import no_style
+from optparse import make_option
 import sys
 
 try:
@@ -8,8 +9,14 @@ except NameError:
     from sets import Set as set   # Python 2.3 fallback
 
 class Command(NoArgsCommand):
+    option_list = NoArgsCommand.option_list + (
+        make_option('--verbosity', action='store', dest='verbosity', default='1',
+            type='choice', choices=['0', '1', '2'],
+            help='Verbosity level; 0=minimal output, 1=normal output, 2=all output'),
+        make_option('--noinput', action='store_false', dest='interactive', default=True,
+            help='Tells Django to NOT prompt the user for input of any kind.'),
+    )
     help = "Create the database tables for all apps in INSTALLED_APPS whose tables haven't already been created."
-    args = '[--verbosity] [--noinput]'
 
     def handle_noargs(self, **options):
         from django.db import connection, transaction, models

django/core/management/commands/test.py

@@ -1,9 +1,17 @@
 from django.core.management.base import BaseCommand
+from optparse import make_option
 import sys
 
 class Command(BaseCommand):
+    option_list = BaseCommand.option_list + (
+        make_option('--verbosity', action='store', dest='verbosity', default='1',
+            type='choice', choices=['0', '1', '2'],
+            help='Verbosity level; 0=minimal output, 1=normal output, 2=all output'),
+        make_option('--noinput', action='store_false', dest='interactive', default=True,
+            help='Tells Django to NOT prompt the user for input of any kind.'),
+    )
     help = 'Runs the test suite for the specified applications, or the entire site if no apps are specified.'
-    args = '[--verbosity] [--noinput] [appname ...]'
+    args = '[appname ...]'
 
     requires_model_validation = False
 

django/core/management/commands/testserver.py

@@ -1,6 +1,13 @@
 from django.core.management.base import BaseCommand
 
+from optparse import make_option
+
 class Command(BaseCommand):
+    option_list = BaseCommand.option_list + (
+        make_option('--verbosity', action='store', dest='verbosity', default='1',
+            type='choice', choices=['0', '1', '2'],
+            help='Verbosity level; 0=minimal output, 1=normal output, 2=all output'),
+    )
     help = 'Runs a development server with data from the given fixture(s).'
     args = '[fixture ...]'
 

django/core/servers/fastcgi.py

@@ -17,14 +17,12 @@ import sys, os
 __version__ = "0.1"
 __all__ = ["runfastcgi"]
 
-FASTCGI_HELP = r"""runfcgi:
+FASTCGI_HELP = r"""
   Run this project as a fastcgi (or some other protocol supported
   by flup) application. To do this, the flup package from
   http://www.saddi.com/software/flup/ is required.
 
-Usage:
+   runfcgi [options] [fcgi settings]
-   django-admin.py runfcgi --settings=yourproject.settings [fcgi settings]
-   manage.py runfcgi [fcgi settings]
 
 Optional Fcgi settings: (setting=value)
   protocol=PROTOCOL    fcgi, scgi, ajp, ... (default fcgi)

docs/django-admin.txt

@@ -35,35 +35,57 @@ be consistent, but any example can use ``manage.py`` just as well.
 Usage
 =====
 
-``django-admin.py action [options]``
+``django-admin.py <subcommand> [options]``
 
-``manage.py action [options]``
+``manage.py <subcommand> [options]``
 
-``action`` should be one of the actions listed in this document. ``options``,
+``subcommand`` should be one of the subcommands listed in this document.
-which is optional, should be zero or more of the options listed in this
+``options``, which is optional, should be zero or more of the options available
-document.
+for the given subcommand.
 
-Run ``django-admin.py --help`` to display a help message that includes a terse
+Getting runtime help
-list of all available actions and options.
+--------------------
 
-Most actions take a list of ``appname``s. An ``appname`` is the basename of the
+In Django 0.96, run ``django-admin.py --help`` to display a help message that
-package containing your models. For example, if your ``INSTALLED_APPS``
+includes a terse list of all available subcommands and options.
-contains the string ``'mysite.blog'``, the ``appname`` is ``blog``.
 
-Available actions
+In the Django development version, run ``django-admin.py help`` to display a
-=================
+list of all available subcommands. Run ``django-admin.py help <subcommand>``
+to display a description of the given subcommand and a list of its available
+options.
 
-adminindex [appname appname ...]
+App names
+---------
+
+Many subcommands take a list of "app names." An "app name" is the basename of
+the package containing your models. For example, if your ``INSTALLED_APPS``
+contains the string ``'mysite.blog'``, the app name is ``blog``.
+
+Determining the version
+-----------------------
+
+Run ``django-admin.py --version`` to display the current Django version.
+
+Examples of output::
+
+	0.95
+    0.96
+    0.97-pre-SVN-6069
+
+Available subcommands
+=====================
+
+adminindex <appname appname ...>
 --------------------------------
 
-Prints the admin-index template snippet for the given appnames.
+Prints the admin-index template snippet for the given app name(s).
 
 Use admin-index template snippets if you want to customize the look and feel of
 your admin's index page. See `Tutorial 2`_ for more information.
 
 .. _Tutorial 2: ../tutorial02/
 
-createcachetable [tablename]
+createcachetable <tablename>
 ----------------------------
 
 Creates a cache table named ``tablename`` for use with the database cache
@@ -100,26 +122,44 @@ example, the default settings don't define ``ROOT_URLCONF``, so
 Note that Django's default settings live in ``django/conf/global_settings.py``,
 if you're ever curious to see the full list of defaults.
 
-dumpdata [appname appname ...]
+dumpdata <appname appname ...>
 ------------------------------
 
-Output to standard output all data in the database associated with the named
+Outputs to standard output all data in the database associated with the named
 application(s).
 
-By default, the database will be dumped in JSON format. If you want the output
-to be in another format, use the ``--format`` option (e.g., ``format=xml``).
-You may specify any Django serialization backend (including any user specified
-serialization backends named in the ``SERIALIZATION_MODULES`` setting). The
-``--indent`` option can be used to pretty-print the output.
-
 If no application name is provided, all installed applications will be dumped.
 
 The output of ``dumpdata`` can be used as input for ``loaddata``.
 
+--format
+~~~~~~~~
+
+By default, ``dumpdata`` will format its output in JSON, but you can use the
+``--format`` option to specify another format. Currently supported formats are
+listed in `Serialization formats`_.
+
+Example usage::
+
+    django-admin.py dumpdata --format=xml
+
+.. _Serialization formats: ../serialization/#Serialization-formats
+
+--indent
+~~~~~~~~
+
+By default, ``dumpdata`` will output all data on a single line. This isn't easy
+for humans to read, so you can use the ``--indent`` option to pretty-print the
+output with a number of indentation spaces.
+
+Example usage::
+
+    django-admin.py dumpdata --indent=4
+
 flush
 -----
 
-Return the database to the state it was in immediately after syncdb was
+Returns the database to the state it was in immediately after syncdb was
 executed. This means that all data will be removed from the database, any
 post-synchronization handlers will be re-executed, and the ``initial_data``
 fixture will be re-installed.
@@ -131,6 +171,27 @@ models and/or weren't in ``INSTALLED_APPS``). Now, the command only clears
 tables that are represented by Django models and are activated in
 ``INSTALLED_APPS``.
 
+--noinput
+~~~~~~~~~
+
+Use the ``--noinput`` option to suppress all user prompting, such as
+"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
+is being executed as an unattended, automated script.
+
+--verbosity
+~~~~~~~~~~~
+
+Use ``--verbosity`` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console.
+
+	* ``0`` means no input.
+	* ``1`` means normal input (default).
+	* ``2`` means verbose input.
+
+Example usage::
+
+    django-admin.py flush --verbosity=2
+
 inspectdb
 ---------
 
@@ -172,15 +233,14 @@ needed.
 ``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
 only works in PostgreSQL and with certain types of MySQL tables.
 
-loaddata [fixture fixture ...]
+loaddata <fixture fixture ...>
 ------------------------------
 
 Searches for and loads the contents of the named fixture into the database.
 
-A *Fixture* is a collection of files that contain the serialized contents of
+A *fixture* is a collection of files that contain the serialized contents of
-the database. Each fixture has a unique name; however, the files that
+the database. Each fixture has a unique name, and the files that comprise the
-comprise the fixture can be distributed over multiple directories, in
+fixture can be distributed over multiple directories, in multiple applications.
-multiple applications.
 
 Django will search in three locations for fixtures:
 
@@ -240,16 +300,37 @@ The ``dumpdata`` command can be used to generate input for ``loaddata``.
     references in your data files - MySQL doesn't provide a mechanism to
     defer checking of row constraints until a transaction is committed.
 
-reset [appname appname ...]
+--verbosity
+~~~~~~~~~~~
+
+Use ``--verbosity`` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console.
+
+	* ``0`` means no input.
+	* ``1`` means normal input (default).
+	* ``2`` means verbose input.
+
+Example usage::
+
+    django-admin.py loaddata --verbosity=2
+
+reset <appname appname ...>
 ---------------------------
 
-Executes the equivalent of ``sqlreset`` for the given appnames.
+Executes the equivalent of ``sqlreset`` for the given app name(s).
+
+--noinput
+~~~~~~~~~
+
+Use the ``--noinput`` option to suppress all user prompting, such as
+"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
+is being executed as an unattended, automated script.
 
 runfcgi [options]
 -----------------
 
-Starts a set of FastCGI processes suitable for use with any web server
+Starts a set of FastCGI processes suitable for use with any Web server
-which supports the FastCGI protocol. See the `FastCGI deployment
+that supports the FastCGI protocol. See the `FastCGI deployment
 documentation`_ for details. Requires the Python FastCGI module from
 `flup`_.
 
@@ -289,6 +370,26 @@ machines on your network. To make your development server viewable to other
 machines on the network, use its own IP address (e.g. ``192.168.2.1``) or
 ``0.0.0.0``.
 
+--adminmedia
+~~~~~~~~~~~~
+
+Use the ``--adminmedia`` option to tell Django where to find the various CSS
+and JavaScript files for the Django admin interface. Normally, the development
+server serves these files out of the Django source tree magically, but you'd
+want to use this if you made any changes to those files for your own site.
+
+Example usage::
+
+    django-admin.py runserver --adminmedia=/tmp/new-admin-style/
+
+--noreload
+~~~~~~~~~~
+
+Use the ``--noreload`` option to disable the use of the auto-reloader. This
+means any Python code changes you make while the server is running will *not*
+take effect if the particular Python modules have already been loaded into
+memory.
+
 Examples:
 ~~~~~~~~~
 
@@ -331,31 +432,31 @@ option, like so::
 
 .. _IPython: http://ipython.scipy.org/
 
-sql [appname appname ...]
+sql <appname appname ...>
 -------------------------
 
-Prints the CREATE TABLE SQL statements for the given appnames.
+Prints the CREATE TABLE SQL statements for the given app name(s).
 
-sqlall [appname appname ...]
+sqlall <appname appname ...>
 ----------------------------
 
-Prints the CREATE TABLE and initial-data SQL statements for the given appnames.
+Prints the CREATE TABLE and initial-data SQL statements for the given app name(s).
 
 Refer to the description of ``sqlcustom`` for an explanation of how to
 specify initial data.
 
-sqlclear [appname appname ...]
+sqlclear <appname appname ...>
 ------------------------------
 
-Prints the DROP TABLE SQL statements for the given appnames.
+Prints the DROP TABLE SQL statements for the given app name(s).
 
-sqlcustom [appname appname ...]
+sqlcustom <appname appname ...>
 -------------------------------
 
-Prints the custom SQL statements for the given appnames.
+Prints the custom SQL statements for the given app name(s).
 
 For each model in each specified app, this command looks for the file
-``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given appname and
+``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given app name and
 ``<modelname>`` is the model's name in lowercase. For example, if you have an
 app ``news`` that includes a ``Story`` model, ``sqlcustom`` will attempt
 to read a file ``news/sql/story.sql`` and append it to the output of this
@@ -373,31 +474,30 @@ sqlflush
 
 Prints the SQL statements that would be executed for the `flush`_ command.
 
-sqlindexes [appname appname ...]
+sqlindexes <appname appname ...>
 --------------------------------
 
-Prints the CREATE INDEX SQL statements for the given appnames.
+Prints the CREATE INDEX SQL statements for the given app name(s).
 
-sqlreset [appname appname ...]
+sqlreset <appname appname ...>
 ------------------------------
 
-Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames.
+Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s).
 
-sqlsequencereset [appname appname ...]
+sqlsequencereset <appname appname ...>
 --------------------------------------
 
-Prints the SQL statements for resetting sequences for the given
+Prints the SQL statements for resetting sequences for the given app name(s).
-appnames.
 
 See http://simon.incutio.com/archive/2004/04/21/postgres for more information.
 
-startapp [appname]
+startapp <appname>
 ------------------
 
 Creates a Django app directory structure for the given app name in the current
 directory.
 
-startproject [projectname]
+startproject <projectname>
 --------------------------
 
 Creates a Django project directory structure for the given project name in the
@@ -435,14 +535,57 @@ with an appropriate extension (e.g. ``json`` or ``xml``). See the
 documentation for ``loaddata`` for details on the specification of fixture
 data files.
 
+--verbosity
+~~~~~~~~~~~
+
+Use ``--verbosity`` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console.
+
+	* ``0`` means no input.
+	* ``1`` means normal input (default).
+	* ``2`` means verbose input.
+
+Example usage::
+
+    django-admin.py syncdb --verbosity=2
+
+--noinput
+~~~~~~~~~
+
+Use the ``--noinput`` option to suppress all user prompting, such as
+"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
+is being executed as an unattended, automated script.
+
 test
 ----
 
-Discover and run tests for all installed models.  See `Testing Django applications`_ for more information.
+Runs tests for all installed models.  See `Testing Django applications`_
+for more information.
 
 .. _testing Django applications: ../testing/
 
-testserver [fixture fixture ...]
+--noinput
+~~~~~~~~~
+
+Use the ``--noinput`` option to suppress all user prompting, such as
+"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
+is being executed as an unattended, automated script.
+
+--verbosity
+~~~~~~~~~~~
+
+Use ``--verbosity`` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console.
+
+	* ``0`` means no input.
+	* ``1`` means normal input (default).
+	* ``2`` means verbose input.
+
+Example usage::
+
+    django-admin.py test --verbosity=2
+
+testserver <fixture fixture ...>
 --------------------------------
 
 **New in Django development version**
@@ -484,29 +627,31 @@ code (as ``runserver`` does). It does, however, detect changes to templates.
 
 .. _unit tests: ../testing/
 
+--verbosity
+~~~~~~~~~~~
+
+Use ``--verbosity`` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console.
+
+	* ``0`` means no input.
+	* ``1`` means normal input (default).
+	* ``2`` means verbose input.
+
+Example usage::
+
+    django-admin.py testserver --verbosity=2
+
 validate
 --------
 
 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
 and prints validation errors to standard output.
 
-Available options
+Default options
-=================
+===============
 
---settings
+Although some subcommands may allow their own custom options, every subcommand
-----------
+allows for the following options:
-
-Example usage::
-
-    django-admin.py syncdb --settings=mysite.settings
-
-Explicitly specifies the settings module to use. The settings module should be
-in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
-``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment
-variable.
-
-Note that this option is unnecessary in ``manage.py``, because it takes care of
-setting ``DJANGO_SETTINGS_MODULE`` for you.
 
 --pythonpath
 ------------
@@ -524,77 +669,20 @@ setting the Python path for you.
 
 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
 
---format
+--settings
---------
-
-Example usage::
-
-    django-admin.py dumpdata --format=xml
-
-Specifies the output format that will be used. The name provided must be the name
-of a registered serializer.
-
---help
-------
-
-Displays a help message that includes a terse list of all available actions and
-options.
-
---indent
---------
-
-Example usage::
-
-    django-admin.py dumpdata --indent=4
-
-Specifies the number of spaces that will be used for indentation when
-pretty-printing output. By default, output will *not* be pretty-printed.
-Pretty-printing will only be enabled if the indent option is provided.
-
---noinput
----------
-
-Inform django-admin that the user should NOT be prompted for any input. Useful
-if the django-admin script will be executed as an unattended, automated
-script.
-
---noreload
 ----------
 
-Disable the use of the auto-reloader when running the development server.
-
---version
----------
-
-Displays the current Django version.
-
-Example output::
-
-    0.9.1
-    0.9.1 (SVN)
-
---verbosity
------------
-
 Example usage::
 
-    django-admin.py syncdb --verbosity=2
+    django-admin.py syncdb --settings=mysite.settings
 
-Verbosity determines the amount of notification and debug information that
+Explicitly specifies the settings module to use. The settings module should be
-will be printed to the console. '0' is no output, '1' is normal output,
+in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
-and ``2`` is verbose output.
+``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment
+variable.
 
---adminmedia
+Note that this option is unnecessary in ``manage.py``, because it takes care of
-------------
+setting ``DJANGO_SETTINGS_MODULE`` for you.
-
-Example usage::
-
-    django-admin.py --adminmedia=/tmp/new-admin-style/
-
-Tells Django where to find the various CSS and JavaScript files for the admin
-interface when running the development server. Normally these files are served
-out of the Django source tree, but because some designers customize these files
-for their site, this option allows you to test against custom versions.
 
 Extra niceties
 ==============