Fixed #14173 -- Added sections about contrib apps-provided commands to django-admin.py docs.

Added documentation about changepassword, pointers to GeoDjango, sitemaps and
staticfiles commands, grouped them by app.

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

4 files changed, 132 insertions, 56 deletions

diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt
index db80b0c908..50bc10c4b6 100644
--- a/docs/ref/contrib/sitemaps.txt
+++ b/docs/ref/contrib/sitemaps.txt
@@ -33,12 +33,12 @@ To install the sitemap app, follow these steps:
 
     1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS`
        setting.
-       
+
     2. Make sure ``'django.template.loaders.app_directories.Loader'``
        is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default,
        so you'll only need to change this if you've changed that setting.
 
-    3. Make sure you've installed the 
+    3. Make sure you've installed the
        :mod:`sites framework <django.contrib.sites>`.
 
 (Note: The sitemap application doesn't install any database tables. The only
@@ -294,7 +294,7 @@ Pinging Google
 ==============
 
 You may want to "ping" Google when your sitemap changes, to let it know to
-reindex your site. The sitemaps framework provides a function to do just 
+reindex your site. The sitemaps framework provides a function to do just
 that: :func:`django.contrib.sitemaps.ping_google()`.
 
 .. function:: ping_google
@@ -313,14 +313,14 @@ that: :func:`django.contrib.sitemaps.ping_google()`.
 
     The :func:`ping_google` command only works if you have registered your
     site with `Google Webmaster Tools`_.
-        
+
 .. _`Google Webmaster Tools`: http://www.google.com/webmasters/tools/
-        
+
 One useful way to call :func:`ping_google` is from a model's ``save()``
 method::
 
    from django.contrib.sitemaps import ping_google
-  
+
     class Entry(models.Model):
         # ...
         def save(self, force_insert=False, force_update=False):
@@ -340,6 +340,8 @@ each time you call ``save()``.
 Pinging Google via `manage.py`
 ------------------------------
 
+.. django-admin:: ping_google
+
 .. versionadded:: 1.0
 
 Once the sitemaps application is added to your project, you may also
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 6d0993c7f0..c6eed32ecf 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -37,26 +37,26 @@ Usage
 
 .. code-block:: bash
 
-    django-admin.py <subcommand> [options]
-    manage.py <subcommand> [options]
+    django-admin.py <command> [options]
+    manage.py <command> [options]
 
-``subcommand`` should be one of the subcommands listed in this document.
+``command`` should be one of the commands listed in this document.
 ``options``, which is optional, should be zero or more of the options available
-for the given subcommand.
+for the given command.
 
 Getting runtime help
 --------------------
 
 .. django-admin-option:: --help
 
-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.
+Run ``django-admin.py help`` to display a list of all available commands.
+Run ``django-admin.py help <command>`` to display a description of the
+given command and a list of its available options.
 
 App names
 ---------
 
-Many subcommands take a list of "app names." An "app name" is the basename of
+Many commands 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``.
 
@@ -80,8 +80,8 @@ Use :djadminopt:`--verbosity` to specify the amount of notification and debug in
 that ``django-admin.py`` should print to the console. For more details, see the
 documentation for the :djadminopt:`--verbosity` option.
 
-Available subcommands
-=====================
+Available commands
+==================
 
 cleanup
 -------
@@ -124,34 +124,6 @@ backend. See :doc:`/topics/cache` for more information.
 The :djadminopt:`--database` option can be used to specify the database
 onto which the cachetable will be installed.
 
-createsuperuser
----------------
-
-.. django-admin:: createsuperuser
-
-.. 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
-do so during ``syncdb``, or if you need to programmatically generate
-superuser accounts for your site(s).
-
-When run interactively, this command will prompt for a password for
-the new superuser account. When run non-interactively, no password
-will be set, and the superuser account will not be able to log in until
-a password has been manually set for it.
-
-.. django-admin-option:: --username
-.. django-admin-option:: --email
-
-The username and e-mail address for the new account can be supplied by
-using the ``--username`` and ``--email`` arguments on the command
-line. If either of those is not supplied, ``createsuperuser`` will prompt for
-it when running interactively.
-
-This command is only available if Django's :doc:`authentication system
-</topics/auth>` (``django.contrib.auth``) is installed.
-
 dbshell
 -------
 
@@ -175,7 +147,6 @@ manually.
 The :djadminopt:`--database` option can be used to specify the database
 onto which to open a shell.
 
-
 diffsettings
 ------------
 
@@ -325,7 +296,6 @@ only works in PostgreSQL and with certain types of MySQL tables.
 The :djadminopt:`--database` option may be used to specify the
 database to introspect.
 
-
 loaddata <fixture fixture ...>
 ------------------------------
 
@@ -878,7 +848,7 @@ templates.
 
 Use ``--addrport`` to specify a different port, or IP address and port, from
 the default of 127.0.0.1:8000. This value follows exactly the same format and
-serves exactly the same function as the argument to the ``runserver`` subcommand.
+serves exactly the same function as the argument to the ``runserver`` command.
 
 Examples:
 
@@ -908,10 +878,113 @@ validate
 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
 and prints validation errors to standard output.
 
+Commands provided by applications
+=================================
+
+Some commands are only available when the ``django.contrib`` application that
+:doc:`implements </howto/custom-management-commands>` them has been
+:setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by
+their application.
+
+``django.contrib.auth``
+-----------------------
+
+changepassword
+~~~~~~~~~~~~~~
+
+.. django-admin:: changepassword
+
+.. versionadded:: 1.2
+
+This command is only available if Django's :doc:`authentication system
+</topics/auth>` (``django.contrib.auth``) is installed.
+
+Allows changing a user's password. It prompts you to enter twice the password of
+the user given as parameter. If they both match, the new password will be
+changed immediately. If you do not supply a user, the command will attempt to
+change the password whose username matches the current user.
+
+Example usage::
+
+    django-admin.py changepassword ringo
+
+createsuperuser
+~~~~~~~~~~~~~~~
+
+.. django-admin:: createsuperuser
+
+.. versionadded:: 1.0
+
+This command is only available if Django's :doc:`authentication system
+</topics/auth>` (``django.contrib.auth``) is installed.
+
+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
+do so during ``syncdb``, or if you need to programmatically generate
+superuser accounts for your site(s).
+
+When run interactively, this command will prompt for a password for
+the new superuser account. When run non-interactively, no password
+will be set, and the superuser account will not be able to log in until
+a password has been manually set for it.
+
+.. django-admin-option:: --username
+.. django-admin-option:: --email
+
+The username and e-mail address for the new account can be supplied by
+using the ``--username`` and ``--email`` arguments on the command
+line. If either of those is not supplied, ``createsuperuser`` will prompt for
+it when running interactively.
+
+``django.contrib.gis``
+----------------------
+
+ogrinspect
+~~~~~~~~~~
+
+This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>`
+(``django.contrib.gis``) is installed.
+
+Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango
+documentation.
+
+``django.contrib.sitemaps``
+---------------------------
+
+ping_google
+~~~~~~~~~~~
+
+This command is only available if the :doc:`Sitemaps framework
+</ref/contrib/sitemaps>` (``django.contrib.sitemaps``) is installed.
+
+Please refer to its :djadmin:`description <ping_google>` in the Sitemaps
+documentation.
+
+``django.contrib.staticfiles``
+------------------------------
+
+collectstatic
+~~~~~~~~~~~~~
+
+This command is only available if the :doc:`static files application
+</howto/static-files>` (``django.contrib.staticfiles``) is installed.
+
+Please refer to its :djadmin:`description <collectstatic>` in the
+:doc:`staticfiles </ref/contrib/staticfiles>` documentation.
+
+findstatic
+~~~~~~~~~~
+
+This command is only available if the :doc:`static files application
+</howto/static-files>` (``django.contrib.staticfiles``) is installed.
+
+Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles
+</ref/contrib/staticfiles>` documentation.
+
 Default options
 ===============
 
-Although some subcommands may allow their own custom options, every subcommand
+Although some commands may allow their own custom options, every command
 allows for the following options:
 
 .. django-admin-option:: --pythonpath
diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index e0856e86ec..1ea15f2fd1 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -37,11 +37,12 @@ Authentication support is bundled as a Django application in
     2. Run the command ``manage.py syncdb``.
 
 Note that the default :file:`settings.py` file created by
-:djadmin:`django-admin.py startproject` includes ``'django.contrib.auth'`` and
-``'django.contrib.contenttypes'`` in :setting:`INSTALLED_APPS` for convenience.
-If your :setting:`INSTALLED_APPS` already contains these apps, feel free to run
-:djadmin:`manage.py syncdb` again; you can run that command as many times as
-you'd like, and each time it'll only install what's needed.
+:djadmin:`django-admin.py startproject <startproject>` includes
+``'django.contrib.auth'`` and ``'django.contrib.contenttypes'`` in
+:setting:`INSTALLED_APPS` for convenience.  If your :setting:`INSTALLED_APPS`
+already contains these apps, feel free to run :djadmin:`manage.py syncdb
+<syncdb>` again; you can run that command as many times as you'd like, and each
+time it'll only install what's needed.
 
 The :djadmin:`syncdb` command creates the necessary database tables, creates
 permission objects for all installed apps that need 'em, and prompts you to
@@ -358,8 +359,8 @@ Changing passwords
 .. versionadded:: 1.2
    The ``manage.py changepassword`` command was added.
 
-:djadmin:`manage.py changepassword <username>` offers a method of
-changing a User's password from the command line. It prompts you to
+:djadmin:`manage.py changepassword *username* <changepassword>` offers a method
+of changing a User's password from the command line. It prompts you to
 change the password of a given user which you must enter twice. If
 they both match, the new password will be changed immediately. If you
 do not supply a user, the command will attempt to change the password
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index 9b72eb3da7..f9f6cc83da 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -272,7 +272,7 @@ in different circumstances.
 Running tests
 =============
 
-Once you've written tests, run them using the :djadmin:`test` subcommand of
+Once you've written tests, run them using the :djadmin:`test` command of
 your project's ``manage.py`` utility::
 
     $ ./manage.py test