From b87454980793dc4364b387f14229b231f276c08c Mon Sep 17 00:00:00 2001 From: Ramiro Morales Date: Sat, 23 Oct 2010 16:37:51 +0000 Subject: [PATCH] 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 --- docs/ref/contrib/sitemaps.txt | 14 +-- docs/ref/django-admin.txt | 157 +++++++++++++++++++++++++--------- docs/topics/auth.txt | 15 ++-- docs/topics/testing.txt | 2 +- 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 `. (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 [options] - manage.py [options] + django-admin.py [options] + manage.py [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 `` 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 `` 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 -` (``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 ------------------------------ @@ -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 ` them has been +:setting:`enabled `. 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 +` (``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 +` (``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 ` +(``django.contrib.gis``) is installed. + +Please refer to its :djadmin:`description ` in the GeoDjango +documentation. + +``django.contrib.sitemaps`` +--------------------------- + +ping_google +~~~~~~~~~~~ + +This command is only available if the :doc:`Sitemaps framework +` (``django.contrib.sitemaps``) is installed. + +Please refer to its :djadmin:`description ` in the Sitemaps +documentation. + +``django.contrib.staticfiles`` +------------------------------ + +collectstatic +~~~~~~~~~~~~~ + +This command is only available if the :doc:`static files application +` (``django.contrib.staticfiles``) is installed. + +Please refer to its :djadmin:`description ` in the +:doc:`staticfiles ` documentation. + +findstatic +~~~~~~~~~~ + +This command is only available if the :doc:`static files application +` (``django.contrib.staticfiles``) is installed. + +Please refer to its :djadmin:`description ` in the :doc:`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 ` 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. 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 ` offers a method of -changing a User's password from the command line. It prompts you to +:djadmin:`manage.py changepassword *username* ` 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