diff --git a/django/core/management/commands/showmigrations.py b/django/core/management/commands/showmigrations.py index b3a4725b12..254b9c5d4c 100644 --- a/django/core/management/commands/showmigrations.py +++ b/django/core/management/commands/showmigrations.py @@ -10,7 +10,7 @@ class Command(BaseCommand): help = "Shows all available migrations for the current project" def add_arguments(self, parser): - parser.add_argument('app_labels', nargs='*', + parser.add_argument('app_label', nargs='*', help='App labels of applications to limit the output to.') parser.add_argument('--database', action='store', dest='database', default=DEFAULT_DB_ALIAS, help='Nominates a database to synchronize. Defaults to the "default" database.') @@ -33,7 +33,7 @@ class Command(BaseCommand): if options['format'] == "plan": return self.show_plan(connection) else: - return self.show_list(connection, options['app_labels']) + return self.show_list(connection, options['app_label']) def show_list(self, connection, app_names=None): """ diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index bc653f78fa..048363122f 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -9,6 +9,7 @@ from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.domains.std import Cmdoption from sphinx.util.compat import Directive from sphinx.util.console import bold from sphinx.util.nodes import set_source_info @@ -46,12 +47,7 @@ def setup(app): indextemplate="pair: %s; django-admin command", parse_node=parse_django_admin_node, ) - app.add_description_unit( - directivename="django-admin-option", - rolename="djadminopt", - indextemplate="pair: %s; django-admin command-line option", - parse_node=parse_django_adminopt_node, - ) + app.add_directive('django-admin-option', Cmdoption) app.add_config_value('django_next_version', '0.0', True) app.add_directive('versionadded', VersionDirective) app.add_directive('versionchanged', VersionDirective) @@ -295,39 +291,10 @@ class DjangoHTMLTranslator(SmartyPantsHTMLTranslator): def parse_django_admin_node(env, sig, signode): command = sig.split(' ')[0] - env._django_curr_admin_command = command + env.ref_context['std:program'] = command title = "django-admin %s" % sig signode += addnodes.desc_name(title, title) - return sig - - -def parse_django_adminopt_node(env, sig, signode): - """A copy of sphinx.directives.CmdoptionDesc.parse_signature()""" - from sphinx.domains.std import option_desc_re - count = 0 - firstname = '' - for m in option_desc_re.finditer(sig): - optname, args = m.groups() - if count: - signode += addnodes.desc_addname(', ', ', ') - signode += addnodes.desc_name(optname, optname) - signode += addnodes.desc_addname(args, args) - if not count: - firstname = optname - count += 1 - if not count: - for m in simple_option_desc_re.finditer(sig): - optname, args = m.groups() - if count: - signode += addnodes.desc_addname(', ', ', ') - signode += addnodes.desc_name(optname, optname) - signode += addnodes.desc_addname(args, args) - if not count: - firstname = optname - count += 1 - if not firstname: - raise ValueError - return firstname + return command class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder): diff --git a/docs/conf.py b/docs/conf.py index 35b82b68b4..cbbeb892ab 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,7 +27,7 @@ sys.path.append(abspath(join(dirname(__file__), "_ext"))) # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.0.8' +needs_sphinx = '1.3' # Actually 1.3.4, but micro versions aren't supported here. # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index 9e338a4bdf..704af90d2d 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -123,8 +123,8 @@ parameter of the handle method. See the :py:mod:`argparse` Python documentation for more about ``add_argument`` usage. In addition to being able to add custom command line options, all -:doc:`management commands` can accept some -default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`. +:doc:`management commands` can accept some default options +such as :option:`--verbosity` and :option:`--traceback`. .. _management-commands-and-locales: @@ -267,9 +267,8 @@ All attributes can be set in your derived class and can be used in see the available styles (use uppercased versions of the "roles" described in that section). - If you pass the :djadminopt:`--no-color` option when running your - command, all ``self.style()`` calls will return the original string - uncolored. + If you pass the :option:`--no-color` option when running your command, all + ``self.style()`` calls will return the original string uncolored. Methods ------- diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt index 1331670a13..59717193dd 100644 --- a/docs/howto/deployment/checklist.txt +++ b/docs/howto/deployment/checklist.txt @@ -32,10 +32,9 @@ module for production. Run ``manage.py check --deploy`` ================================ -Some of the checks described below can be automated using the -:djadminopt:`--deploy` option of the :djadmin:`check` command. Be sure to run it -against your production settings file as described in the option's -documentation. +Some of the checks described below can be automated using the :option:`check +--deploy` option. Be sure to run it against your production settings file as +described in the option's documentation. Critical settings ================= diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 13bfe88290..c48248fb79 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -241,7 +241,8 @@ __ http://sphinx-doc.org/markup/ .. django-admin-option:: --traceback - To link, use ``:djadminopt:`--traceback```. + To link, use ``:option:`command_name --traceback``` (or omit ``command_name`` + for the options shared by all commands like ``--verbosity``). * Links to Trac tickets (typically reserved for patch release notes):: diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index c03da8fd47..d5add78423 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -372,10 +372,9 @@ details on these changes. ``get_backend_timeout()`` will be removed. * The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` will be removed. - Use :djadminopt:`--natural-foreign` instead. * The ``use_natural_keys`` argument for ``serializers.serialize()`` will be - removed. Use ``use_natural_foreign_keys`` instead. + removed. * Private API ``django.forms.forms.get_declared_fields()`` will be removed. diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index cf93a61c79..e9c8e45cbb 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -69,6 +69,8 @@ class name. Builtin checks ============== +.. _system-check-builtin-tags: + Builtin tags ------------ @@ -449,8 +451,7 @@ balancer, it'd be irritating to be constantly warned about not having enabled :setting:`SECURE_SSL_REDIRECT`. Use :setting:`SILENCED_SYSTEM_CHECKS` to silence unneeded checks. -The following checks will be run if you use the :djadminopt:`--deploy` option -of the :djadmin:`check` command: +The following checks are run if you use the :option:`check --deploy` option: * **security.W001**: You do not have :class:`django.middleware.security.SecurityMiddleware` in your diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 0d75739e48..343ede1949 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -320,8 +320,7 @@ model: generic relations, you should probably be using a natural key to uniquely identify related :class:`~django.contrib.contenttypes.models.ContentType` objects. See :ref:`natural keys` and - :djadminopt:`dumpdata --natural-foreign <--natural-foreign>` for more - information. + :option:`dumpdata --natural-foreign` for more information. This will enable an API similar to the one used for a normal :class:`~django.db.models.ForeignKey`; diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index d22621aafe..71f3863f4b 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -12,35 +12,35 @@ When :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`, the The overridden command is spatially-aware, and places geometry fields in the auto-generated model definition, where appropriate. -ogrinspect -===================================== +ogrinspect +========== -.. django-admin:: ogrinspect +.. django-admin:: ogrinspect data_source model_name The ``ogrinspect`` management command will inspect the given OGR-compatible :class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will output a GeoDjango model with the given model name. There's a detailed example of using ``ogrinspect`` :ref:`in the tutorial `. -.. django-admin-option:: --blank +.. django-admin-option:: --blank BLANK Use a comma separated list of OGR field names to add the ``blank=True`` keyword option to the field definition. Set with ``true`` to apply to all applicable fields. -.. django-admin-option:: --decimal +.. django-admin-option:: --decimal DECIMAL Use a comma separated list of OGR float fields to generate :class:`~django.db.models.DecimalField` instead of the default :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all OGR float fields. -.. django-admin-option:: --geom-name +.. django-admin-option:: --geom-name GEOM_NAME Specifies the model attribute name to use for the geometry field. Defaults to ``'geom'``. -.. django-admin-option:: --layer +.. django-admin-option:: --layer LAYER_KEY The key for specifying which layer in the OGR :class:`~django.contrib.gis.gdal.DataSource` source to use. @@ -61,7 +61,7 @@ of using ``ogrinspect`` :ref:`in the tutorial `. in the generated model rather than :class:`~django.contrib.gis.db.models.PolygonField`. -.. django-admin-option:: --name-field +.. django-admin-option:: --name-field NAME_FIELD Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model that will return the given field name. @@ -70,13 +70,13 @@ of using ``ogrinspect`` :ref:`in the tutorial `. Suppresses the ``from django.contrib.gis.db import models`` import statement. -.. django-admin-option:: --null +.. django-admin-option:: --null NULL Use a comma separated list of OGR field names to add the ``null=True`` keyword option to the field definition. Set with ``true`` to apply to all applicable fields. -.. django-admin-option:: --srid +.. django-admin-option:: --srid SRID The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts to automatically determine of the SRID of the data source. diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 822b338e2e..58c5e71a31 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -519,7 +519,7 @@ each time you call ``save()``. Pinging Google via ``manage.py`` -------------------------------- -.. django-admin:: ping_google +.. django-admin:: ping_google [sitemap_url] Once the sitemaps application is added to your project, you may also ping Google using the ``ping_google`` management command:: diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index e6caa53e32..b6da4b98d2 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -49,8 +49,8 @@ can help show you which files are found. On subsequent ``collectstatic`` runs (if ``STATIC_ROOT`` isn't empty), files are copied only if they have a modified timestamp greater than the timestamp of the file in ``STATIC_ROOT``. Therefore if you remove an application from -:setting:`INSTALLED_APPS`, it's a good idea to use the :djadminopt:`--clear` -option in order to remove stale static files. +:setting:`INSTALLED_APPS`, it's a good idea to use the :option:`collectstatic +--clear` option in order to remove stale static files. Files are searched by using the :setting:`enabled finders `. The default is to look in all locations defined in @@ -88,33 +88,28 @@ Then set the :setting:`STATICFILES_STORAGE` setting to Some commonly used options are: -.. django-admin-option:: --noinput +.. django-admin-option:: --noinput, --no-input - Do NOT prompt the user for input of any kind. You can use ``--no-input`` - as an alias for this option. + Do NOT prompt the user for input of any kind. .. versionchanged:: 1.9 The ``--no-input`` alias was added. -.. django-admin-option:: -i -.. django-admin-option:: --ignore +.. django-admin-option:: --ignore PATTERN, -i PATTERN Ignore files or directories matching this glob-style pattern. Use multiple times to ignore more. -.. django-admin-option:: -n -.. django-admin-option:: --dry-run +.. django-admin-option:: --dry-run, -n Do everything except modify the filesystem. -.. django-admin-option:: -c -.. django-admin-option:: --clear +.. django-admin-option:: --clear, -c Clear the existing files before trying to copy or link the original file. -.. django-admin-option:: -l -.. django-admin-option:: --link +.. django-admin-option:: --link, -l Create a symbolic link to each file instead of copying. @@ -136,7 +131,7 @@ For a full list of options, refer to the commands own help by running:: findstatic ---------- -.. django-admin:: findstatic +.. django-admin:: findstatic static file [static file ...] Searches for one or more relative paths with the enabled finders. @@ -149,6 +144,8 @@ For example:: Found 'admin/js/core.js' here: /home/polls.com/src/django/contrib/admin/media/js/core.js +.. django-admin-option:: findstatic --first + By default, all matching locations are found. To only return the first match for each relative path, use the ``--first`` option:: @@ -159,15 +156,15 @@ for each relative path, use the ``--first`` option:: This is a debugging aid; it'll show you exactly which static file will be collected for a given path. -By setting the :djadminopt:`--verbosity` flag to 0, you can suppress the extra -output and just get the path names:: +By setting the ``--verbosity`` flag to 0, you can suppress the extra output and +just get the path names:: $ python manage.py findstatic css/base.css --verbosity 0 /home/special.polls.com/core/static/css/base.css /home/polls.com/core/static/css/base.css -On the other hand, by setting the :djadminopt:`--verbosity` flag to 2, you can -get all the directories which were searched:: +On the other hand, by setting the ``--verbosity`` flag to 2, you can get all +the directories which were searched:: $ python manage.py findstatic css/base.css --verbosity 2 Found 'css/base.css' here: @@ -183,7 +180,7 @@ get all the directories which were searched:: runserver --------- -.. django-admin:: runserver +.. django-admin:: runserver [addrport] Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app is :setting:`installed` and adds automatic serving of static diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 80e40485db..a0d9e54296 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -27,7 +27,7 @@ Environment...``) to point to its installed location. Generally, when working on a single Django project, it's easier to use ``manage.py`` than ``django-admin``. If you need to switch between multiple Django settings files, use ``django-admin`` with -:envvar:`DJANGO_SETTINGS_MODULE` or the :djadminopt:`--settings` command line +:envvar:`DJANGO_SETTINGS_MODULE` or the :option:`--settings` command line option. The command-line examples throughout this document use ``django-admin`` to @@ -88,50 +88,45 @@ The output follows the schema described in :pep:`440`:: Displaying debug output ----------------------- -Use :djadminopt:`--verbosity` to specify the amount of notification and debug information -that ``django-admin`` should print to the console. For more details, see the -documentation for the :djadminopt:`--verbosity` option. +.. program:: None + +Use :option:`--verbosity` to specify the amount of notification and debug +information that ``django-admin`` prints to the console. Available commands ================== -check ---------------------------- +check +----- -.. django-admin:: check +.. django-admin:: check [app_label [app_label ...]] -Uses the :doc:`system check framework ` to inspect -the entire Django project for common problems. +Uses the :doc:`system check framework ` to inspect the entire +Django project for common problems. -The system check framework will confirm that there aren't any problems with -your installed models or your admin registrations. It will also provide warnings -of common compatibility problems introduced by upgrading Django to a new version. -Custom checks may be introduced by other libraries and applications. +By default, all apps will be checked. You can check a subset of apps by +providing a list of app labels as arguments:: -By default, all apps will be checked. You can check a subset of apps by providing -a list of app labels as arguments:: - - python manage.py check auth admin myapp + django-admin check auth admin myapp If you do not specify any app, all apps will be checked. -.. django-admin-option:: --tag +.. django-admin-option:: --tag TAGS, -t TAGS -The :doc:`system check framework ` performs many different -types of checks. These check types are categorized with tags. You can use these tags -to restrict the checks performed to just those in a particular category. For example, -to perform only security and compatibility checks, you would run:: +The system check framework performs many different types of checks that are +:ref:`categorized with tags `. You can use these +tags to restrict the checks performed to just those in a particular category. +For example, to perform only models and compatibility checks, run:: - python manage.py check --tag security --tag compatibility + django-admin check --tag models --tag compatibility .. django-admin-option:: --list-tags -List all available tags. +Lists all available tags. .. django-admin-option:: --deploy -The ``--deploy`` option activates some additional checks that are only relevant -in a deployment setting. +Activates some additional checks that are only relevant in a deployment setting. You can use this option in your local development environment, but since your local development settings module may not have many of your production settings, @@ -139,39 +134,39 @@ you will probably want to point the ``check`` command at a different settings module, either by setting the ``DJANGO_SETTINGS_MODULE`` environment variable, or by passing the ``--settings`` option:: - python manage.py check --deploy --settings=production_settings + django-admin check --deploy --settings=production_settings Or you could run it directly on a production or staging deployment to verify that the correct settings are in use (omitting ``--settings``). You could even make it part of your integration test suite. -.. django-admin-option:: --fail-level +.. django-admin-option:: --fail-level {CRITICAL,ERROR,WARNING,INFO,DEBUG} .. versionadded:: 1.10 Specifies the message level that will cause the command to exit with a non-zero status. Default is ``ERROR``. -Available levels are: ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, and -``DEBUG``. - compilemessages --------------- .. django-admin:: compilemessages -Compiles .po files created by :djadmin:`makemessages` to .mo files for use with -the builtin gettext support. See :doc:`/topics/i18n/index`. +Compiles ``.po`` files created by :djadmin:`makemessages` to ``.mo`` files for +use with the built-in gettext support. See :doc:`/topics/i18n/index`. -Use the :djadminopt:`--locale` option (or its shorter version ``-l``) to -specify the locale(s) to process. If not provided, all locales are processed. +.. django-admin-option:: --locale LOCALE, -l LOCALE -Use the :djadminopt:`--exclude` option (or its shorter version ``-x``) to -specify the locale(s) to exclude from processing. If not provided, no locales +Specifies the locale(s) to process. If not provided, all locales are processed. + +.. django-admin-option:: --exclude EXCLUDE, -x EXCLUDE + +Specifies the locale(s) to exclude from processing. If not provided, no locales are excluded. -You can pass ``--use-fuzzy`` option (or ``-f``) to include fuzzy translations -into compiled files. +.. django-admin-option:: --use-fuzzy, -f + +Includes fuzzy translations into compiled files. .. versionchanged:: 1.9 @@ -198,12 +193,15 @@ Creates the cache tables for use with the database cache backend using the information from your settings file. See :doc:`/topics/cache` for more information. -The :djadminopt:`--database` option can be used to specify the database -onto which the cache table will be installed, but since this information is -pulled from your settings by default, it's typically not needed. +.. django-admin-option:: --database DATABASE -The :djadminopt:`--dry-run` option will print the SQL that would be run without -actually running it, so you can customize it or use the migrations framework. +Specifies the database in which the cache table(s) will be created. Defaults to +``default``. + +.. django-admin-option:: --dry-run + +Prints the SQL that would be run without actually running it, so you can +customize it or use the migrations framework. .. versionchanged:: 1.9 @@ -215,8 +213,8 @@ dbshell .. django-admin:: dbshell Runs the command-line client for the database engine specified in your -``ENGINE`` setting, with the connection parameters specified in your -:setting:`USER`, :setting:`PASSWORD`, etc., settings. +:setting:`ENGINE ` setting, with the connection parameters +specified in your :setting:`USER`, :setting:`PASSWORD`, etc., settings. * For PostgreSQL, this runs the ``psql`` command-line client. * For MySQL, this runs the ``mysql`` command-line client. @@ -228,8 +226,9 @@ the program name (``psql``, ``mysql``, ``sqlite3``, ``sqlplus``) will find the program in the right place. There's no way to specify the location of the program manually. -The :djadminopt:`--database` option can be used to specify the database -onto which to open a shell. +.. django-admin-option:: --database DATABASE + +Specifies the database onto which to open a shell. Defaults to ``default``. diffsettings ------------ @@ -244,13 +243,15 @@ example, the default settings don't define :setting:`ROOT_URLCONF`, so :setting:`ROOT_URLCONF` is followed by ``"###"`` in the output of ``diffsettings``. -The :djadminopt:`--all` option may be provided to display all settings, even -if they have Django's default value. Such settings are prefixed by ``"###"``. +.. django-admin-option:: --all -dumpdata --------------------------------------------------- +Displays all settings, even if they have Django's default value. Such settings +are prefixed by ``"###"``. -.. django-admin:: dumpdata +dumpdata +-------- + +.. django-admin:: dumpdata [app_label[.ModelName] [app_label[.ModelName] ...]] Outputs to standard output all data in the database associated with the named application(s). @@ -264,59 +265,63 @@ records to dump. If you're using a :ref:`custom manager ` as the default manager and it filters some of the available records, not all of the objects will be dumped. -The :djadminopt:`--all` option may be provided to specify that -``dumpdata`` should use Django's base manager, dumping records which -might otherwise be filtered or modified by a custom manager. +.. django-admin-option:: --all, -a -.. django-admin-option:: --format +Uses Django's base manager, dumping records which might otherwise be filtered +or modified by a custom manager. -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 :ref:`serialization-formats`. +.. django-admin-option:: --format FORMAT -.. django-admin-option:: --indent +Specifies the serialization format of the output. Defaults to JSON. Supported +formats are listed in :ref:`serialization-formats`. -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. +.. django-admin-option:: --indent INDENT -The :djadminopt:`--exclude` option may be provided to prevent specific -applications or models (specified as in the form of ``app_label.ModelName``) -from being dumped. If you specify a model name to ``dumpdata``, the dumped +Specifies the number of indentation spaces to use in the output. Defaults to +``None`` which displays all data on single line. + +.. django-admin-option:: --exclude EXCLUDE, -e EXCLUDE + +Prevents specific applications or models (specified in the form of +``app_label.ModelName``) from being dumped. If you specify a model name, the output will be restricted to that model, rather than the entire application. You can also mix application names and model names. -The :djadminopt:`--database` option can be used to specify the database -from which data will be dumped. +If you want to exclude multiple applications, pass ``--exclude`` more than +once:: + + django-admin dumpdata --exclude=auth --exclude=contenttypes + +.. django-admin-option:: --database DATABASE + +Specifies the database from which data will be dumped. Defaults to ``default``. .. django-admin-option:: --natural-foreign -When this option is specified, Django will use the ``natural_key()`` model -method to serialize any foreign key and many-to-many relationship to objects of -the type that defines the method. If you are dumping ``contrib.auth`` -``Permission`` objects or ``contrib.contenttypes`` ``ContentType`` objects, you -should probably be using this flag. See the :ref:`natural keys -` documentation for more details on this -and the next option. +Uses the ``natural_key()`` model method to serialize any foreign key and +many-to-many relationship to objects of the type that defines the method. If +you're dumping ``contrib.auth`` ``Permission`` objects or +``contrib.contenttypes`` ``ContentType`` objects, you should probably use this +flag. See the :ref:`natural keys ` +documentation for more details on this and the next option. .. django-admin-option:: --natural-primary -When this option is specified, Django will not provide the primary key in the -serialized data of this object since it can be calculated during -deserialization. +Omits the primary key in the serialized data of this object since it can be +calculated during deserialization. -.. django-admin-option:: --pks +.. django-admin-option:: --pks PRIMARY_KEYS -By default, ``dumpdata`` will output all the records of the model, but -you can use the ``--pks`` option to specify a comma separated list of -primary keys on which to filter. This is only available when dumping -one model. +Outputs only the objects specified by a comma separated list of primary keys. +This is only available when dumping one model. By default, all the records of +the model are output. -.. django-admin-option:: --output +.. django-admin-option:: --output OUTPUT, -o OUTPUT -By default ``dumpdata`` will output all the serialized data to standard output. -This option allows you to specify the file to which the data is to be written. -When this option is set and the verbosity is greater than 0 (the default), a +Specifies a file to write the serialized data to. By default, the data goes to +standard output. + +When this option is set and ``--verbosity`` is greater than 0 (the default), a progress bar is shown in the terminal. .. versionchanged:: 1.9 @@ -334,11 +339,17 @@ handlers. The table of which migrations have been applied is not cleared. If you would rather start from an empty database and re-run all migrations, you should drop and recreate the database and then run :djadmin:`migrate` instead. -The :djadminopt:`--noinput` option may be provided to suppress all user -prompts. +.. django-admin-option:: --noinput, --no-input -The :djadminopt:`--database` option may be used to specify the database -to flush. +Suppresses all user prompts. + +.. versionchanged:: 1.9 + + The ``--no-input`` alias was added. + +.. django-admin-option:: --database DATABASE + +Specifies the database to flush. Defaults to ``default``. inspectdb --------- @@ -395,28 +406,30 @@ table's lifecycle, you'll need to change the :attr:`~django.db.models.Options.managed` option to ``True`` (or simply remove it because ``True`` is its default value). -The :djadminopt:`--database` option may be used to specify the -database to introspect. +.. django-admin-option:: --database DATABASE -loaddata ------------------------------- +Specifies the database to introspect. Defaults to ``default``. -.. django-admin:: loaddata +loaddata +-------- + +.. django-admin:: loaddata fixture [fixture ...] Searches for and loads the contents of the named fixture into the database. -The :djadminopt:`--database` option can be used to specify the database -onto which the data will be loaded. +.. django-admin-option:: --database DATABASE -.. django-admin-option:: --ignorenonexistent +Specifies the database into which the data will be loaded. Defaults to +``default``. -The :djadminopt:`--ignorenonexistent` option can be used to ignore fields and -models that may have been removed since the fixture was originally generated. +.. django-admin-option:: --ignorenonexistent, -i -.. django-admin-option:: --app +Ignores fields and models that may have been removed since the fixture was +originally generated. -The :djadminopt:`--app` option can be used to specify a single app to look -for fixtures in rather than looking through all apps. +.. django-admin-option:: --app APP_LABEL + +Specifies a single app to look for fixtures in rather than looking in all apps. What's a "fixture"? ~~~~~~~~~~~~~~~~~~~ @@ -558,33 +571,31 @@ directory. After making changes to the messages files you need to compile them with :djadmin:`compilemessages` for use with the builtin gettext support. See the :ref:`i18n documentation ` for details. -.. django-admin-option:: --all +.. django-admin-option:: --all, -a -Use the ``--all`` or ``-a`` option to update the message files for all -available languages. +Updates the message files for all available languages. -Example usage:: +.. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS - django-admin makemessages --all - -.. django-admin-option:: --extension - -Use the ``--extension`` or ``-e`` option to specify a list of file extensions -to examine (default: ".html", ".txt"). +Specifies a list of file extensions to examine (default: ``html``, ``txt``, +``py`` or ``js`` if :option:`--domain` is ``js``). Example usage:: django-admin makemessages --locale=de --extension xhtml -Separate multiple extensions with commas or use -e or --extension multiple times:: +Separate multiple extensions with commas or use ``-e`` or ``--extension`` +multiple times:: django-admin makemessages --locale=de --extension=html,txt --extension xml -Use the :djadminopt:`--locale` option (or its shorter version ``-l``) to -specify the locale(s) to process. +.. django-admin-option:: --locale LOCALE, -l LOCALE -Use the :djadminopt:`--exclude` option (or its shorter version ``-x``) to -specify the locale(s) to exclude from processing. If not provided, no locales +Specifies the locale(s) to process. + +.. django-admin-option:: --exclude EXCLUDE, -x EXCLUDE + +Specifies the locale(s) to exclude from processing. If not provided, no locales are excluded. Example usage:: @@ -598,29 +609,27 @@ Example usage:: django-admin makemessages -x pt_BR django-admin makemessages -x pt_BR -x fr -.. django-admin-option:: --domain +.. django-admin-option:: --domain DOMAIN, -d DOMAIN -Use the ``--domain`` or ``-d`` option to change the domain of the messages files. -Currently supported: +Specifies the domain of the messages files. Supported options are: * ``django`` for all ``*.py``, ``*.html`` and ``*.txt`` files (default) * ``djangojs`` for ``*.js`` files -.. django-admin-option:: --symlinks +.. django-admin-option:: --symlinks, -s -Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when -looking for new translation strings. +Follows symlinks to directories when looking for new translation strings. Example usage:: django-admin makemessages --locale=de --symlinks -.. django-admin-option:: --ignore +.. django-admin-option:: --ignore PATTERN, -i PATTERN -Use the ``--ignore`` or ``-i`` option to ignore files or directories matching -the given :mod:`glob`-style pattern. Use multiple times to ignore more. +Ignores files or directories matching the given :mod:`glob`-style pattern. Use +multiple times to ignore more. -These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``, ``'*.pyc'`` +These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``, ``'*.pyc'``. Example usage:: @@ -628,35 +637,33 @@ Example usage:: .. django-admin-option:: --no-default-ignore -Use the ``--no-default-ignore`` option to disable the default values of -:djadminopt:`--ignore`. +Disables the default values of ``--ignore``. .. django-admin-option:: --no-wrap -Use the ``--no-wrap`` option to disable breaking long message lines into -several lines in language files. +Disables breaking long message lines into several lines in language files. .. django-admin-option:: --no-location -Use the ``--no-location`` option to suppress writing '``#: filename:line``’ -comment lines in language files. Note that using this option makes it harder -for technically skilled translators to understand each message's context. +Suppresses writing '``#: filename:line``’ comment lines in language files. +Using this option makes it harder for technically skilled translators to +understand each message's context. .. django-admin-option:: --keep-pot -Use the ``--keep-pot`` option to prevent Django from deleting the temporary -``.pot`` files it generates before creating the .po file. This is useful for -debugging errors which may prevent the final language files from being created. +Prevents deleting the temporary ``.pot`` files generated before creating the +``.po`` file. This is useful for debugging errors which may prevent the final +language files from being created. .. seealso:: See :ref:`customizing-makemessages` for instructions on how to customize the keywords that :djadmin:`makemessages` passes to ``xgettext``. -makemigrations [] ----------------------------- +makemigrations +-------------- -.. django-admin:: makemigrations +.. django-admin:: makemigrations [app_label [app_label ...]] Creates new migrations based on the changes detected to your models. Migrations, their relationship with apps and more are covered in depth in @@ -666,56 +673,56 @@ Providing one or more app names as arguments will limit the migrations created to the app(s) specified and any dependencies needed (the table at the other end of a ``ForeignKey``, for example). +.. django-admin-option:: --noinput, --no-input + +Suppresses all user prompts. If a suppressed prompt cannot be resolved +automatically, the command will exit with error code 3. + .. versionchanged:: 1.9 -The ``--noinput`` option may be provided to suppress all user prompts. If a suppressed -prompt cannot be resolved automatically, the command will exit with error code 3. + The ``--no-input`` alias was added. .. django-admin-option:: --empty -The ``--empty`` option will cause ``makemigrations`` to output an empty -migration for the specified apps, for manual editing. This option is only -for advanced users and should not be used unless you are familiar with -the migration format, migration operations, and the dependencies between -your migrations. +Outputs an empty migration for the specified apps, for manual editing. This is +for advanced users and should not be used unless you are familiar with the +migration format, migration operations, and the dependencies between your +migrations. .. django-admin-option:: --dry-run -The ``--dry-run`` option shows what migrations would be made without -actually writing any migrations files to disk. Using this option along with -``--verbosity 3`` will also show the complete migrations files that would be -written. +Shows what migrations would be made without actually writing any migrations +files to disk. Using this option along with ``--verbosity 3`` will also show +the complete migrations files that would be written. .. django-admin-option:: --merge -The ``--merge`` option enables fixing of migration conflicts. +Enables fixing of migration conflicts. -.. django-admin-option:: --name, -n +.. django-admin-option:: --name NAME, -n NAME -The ``--name`` option allows you to give the migration(s) a custom name instead -of a generated one. +Allows naming the generated migration(s) instead of using a generated name. .. django-admin-option:: --exit, -e .. deprecated:: 1.10 - Use the :djadminopt:`--check` option instead. + Use the ``--check`` option instead. -The ``--exit`` option will cause ``makemigrations`` to exit with error code 1 -when no migrations are created (or would have been created, if combined with -``--dry-run``). +Makes ``makemigrations`` exit with error code 1 when no migrations are created +(or would have been created, if combined with ``--dry-run``). .. django-admin-option:: --check .. versionadded:: 1.10 -The ``--check`` option makes ``makemigrations`` exit with a non-zero status -when model changes without migrations are detected. +Makes ``makemigrations`` exit with a non-zero status when model changes without +migrations are detected. -migrate [ []] ---------------------------------------- +migrate +------- -.. django-admin:: migrate +.. django-admin:: migrate [app_label] [migration_name] Synchronizes the database state with the current set of models and migrations. Migrations, their relationship with apps and more are covered in depth in @@ -733,14 +740,14 @@ The behavior of this command changes depending on the arguments provided: migrated past the named migration. Use the name ``zero`` to unapply all migrations for an app. -The :djadminopt:`--database` option can be used to specify the database to -migrate. +.. django-admin-option:: --database DATABASE + +Specifies the database to migrate. Defaults to ``default``. .. django-admin-option:: --fake -The ``--fake`` option tells Django to mark the migrations as having been -applied or unapplied, but without actually running the SQL to change your -database schema. +Tells Django to mark the migrations as having been applied or unapplied, but +without actually running the SQL to change your database schema. This is intended for advanced users to manipulate the current migration state directly if they're manually applying changes; @@ -750,9 +757,9 @@ run correctly. .. django-admin-option:: --fake-initial -The ``--fake-initial`` option can be used to allow Django to skip an app's -initial migration if all database tables with the names of all models created -by all :class:`~django.db.migrations.operations.CreateModel` operations in that +Allows Django to skip an app's initial migration if all database tables with +the names of all models created by all +:class:`~django.db.migrations.operations.CreateModel` operations in that migration already exist. This option is intended for use when first running migrations against a database that preexisted the use of migrations. This option does not, however, check for matching database schema beyond matching @@ -763,14 +770,14 @@ schema matches what is recorded in your initial migration. .. versionadded:: 1.9 -The ``--run-syncdb`` option allows creating tables for apps without migrations. -While this isn't recommended, the migrations framework is sometimes too slow -on large projects with hundreds of models. +Allows creating tables for apps without migrations. While this isn't +recommended, the migrations framework is sometimes too slow on large projects +with hundreds of models. -runserver [port or address:port] --------------------------------- +runserver +--------- -.. django-admin:: runserver +.. django-admin:: runserver [addrport] Starts a lightweight development Web server on the local machine. By default, the server runs on port 8000 on the IP address ``127.0.0.1``. You can pass in an @@ -837,30 +844,20 @@ Logging of each request and response of the server is sent to the .. django-admin-option:: --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. - -Example usage:: - - django-admin runserver --noreload +Disables 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. .. django-admin-option:: --nothreading -The development server is multithreaded by default. Use the ``--nothreading`` -option to disable the use of threading in the development server. +Disables use of threading in the development server. The server is +multithreaded by default. .. django-admin-option:: --ipv6, -6 -Use the ``--ipv6`` (or shorter ``-6``) option to tell Django to use IPv6 for -the development server. This changes the default IP address from +Uses IPv6 for the development server. This changes the default IP address from ``127.0.0.1`` to ``::1``. -Example usage:: - - django-admin runserver --ipv6 - Examples of using different ports and addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -911,7 +908,7 @@ you want to configure Django to serve static media, read sendtestemail ------------- -.. django-admin:: sendtestemail +.. django-admin:: sendtestemail [email [email ...]] .. versionadded:: 1.9 @@ -920,17 +917,18 @@ recipient(s) specified. For example:: django-admin sendtestemail foo@example.com bar@example.com +There are a couple of options, and you may use any combination of them +together: + .. django-admin-option:: --managers -Use the ``--managers`` option to mail the email addresses specified in -:setting:`MANAGERS` using :meth:`~django.core.mail.mail_managers()`. +Mails the email addresses specified in :setting:`MANAGERS` using +:meth:`~django.core.mail.mail_managers()`. .. django-admin-option:: --admins -Use the ``--admins`` option to mail the email addresses specified in -:setting:`ADMINS` using :meth:`~django.core.mail.mail_admins()`. - -Note that you may use any combination of these options together. +Mails the email addresses specified in :setting:`ADMINS` using +:meth:`~django.core.mail.mail_admins()`. shell ----- @@ -939,77 +937,74 @@ shell Starts the Python interactive interpreter. -Django will use IPython_ or bpython_ if either is installed. If you have a -rich shell installed but want to force use of the "plain" Python interpreter, -use the ``-i python`` or ``--interface python`` option, like so:: +.. django-admin-option:: --interface {ipython,bpython,python}, -i {ipython,bpython,python} - django-admin shell -i python - django-admin shell --interface python - -.. deprecated:: 1.10 - - In older versions, use the ``--plain`` option. This is deprecated and will - be removed in Django 2.0. - -If you would like to specify either IPython or bpython as your interpreter if -you have both installed you can specify an alternative interpreter interface -with the ``-i`` or ``--interface`` options like so: +Specifies the shell to use. By default, Django will use IPython_ or bpython_ if +either is installed. If both are installed, specify which one you want like so: IPython:: django-admin shell -i ipython - django-admin shell --interface ipython - bpython:: django-admin shell -i bpython - django-admin shell --interface bpython +If you have a "rich" shell installed but want to force use of the "plain" +Python interpreter, use ``python`` as the interface name, like so:: + + django-admin shell -i python + +.. deprecated:: 1.10 + + In older versions, use the ``--plain`` option instead of ``-i python``. This + is deprecated and will be removed in Django 2.0. .. _IPython: http://ipython.scipy.org/ .. _bpython: http://bpython-interpreter.org/ -When the "plain" Python interactive interpreter starts (be it because -``--interface python`` was specified or because no other interactive interface -is available) it reads the script pointed to by the :envvar:`PYTHONSTARTUP` -environment variable and the ``~/.pythonrc.py`` script. If you don't wish this -behavior you can use the ``--no-startup`` option. e.g.:: +.. django-admin-option:: --nostartup - django-admin shell --interface python --no-startup +Disables reading the startup script for the "plain" Python interpreter. By +default, the script pointed to by the :envvar:`PYTHONSTARTUP` environment +variable or the ``~/.pythonrc.py`` script is read. -.. django-admin-option:: --command, -c +.. django-admin-option:: --command COMMAND, -c COMMAND .. versionadded:: 1.10 -The ``--command`` option lets you pass a command as a string to execute it as -Django, like so:: +Lets you pass a command as a string to execute it as Django, like so:: django-admin shell --command="import django; print(django.__version__)" -showmigrations [ []] ------------------------------------------- +showmigrations +-------------- -.. django-admin:: showmigrations +.. django-admin:: showmigrations [app_label [app_label ...]] -Shows all migrations in a project. +Shows all migrations in a project. You can choose from one of two formats: .. django-admin-option:: --list, -l -The ``--list`` option lists all of the apps Django knows about, the -migrations available for each app, and whether or not each migration is -applied (marked by an ``[X]`` next to the migration name). +Lists all of the apps Django knows about, the migrations available for each +app, and whether or not each migration is applied (marked by an ``[X]`` next to +the migration name). Apps without migrations are also listed, but have ``(no migrations)`` printed under them. +This is the default output format. + .. django-admin-option:: --plan, -p -The ``--plan`` option shows the migration plan Django will follow to apply -migrations. Any supplied app labels are ignored because the plan might go -beyond those apps. Same as ``--list``, applied migrations are marked by an -``[X]``. For a verbosity of 2 and above, all dependencies of a migration will -also be shown. +Shows the migration plan Django will follow to apply migrations. Any supplied +app labels are ignored because the plan might go beyond those apps. Like +``--list``, applied migrations are marked by an ``[X]``. For a ``--verbosity`` +of 2 and above, all dependencies of a migration will also be shown. + +.. django-admin-option:: --database DATABASE + +Specifies the database to examine. Defaults to ``default``. sqlflush -------- @@ -1019,13 +1014,14 @@ sqlflush Prints the SQL statements that would be executed for the :djadmin:`flush` command. -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. +.. django-admin-option:: --database DATABASE -sqlmigrate --------------------------------------- +Specifies the database for which to print the SQL. Defaults to ``default``. -.. django-admin:: sqlmigrate +sqlmigrate +---------- + +.. django-admin:: sqlmigrate app_label migration_name Prints the SQL for the named migration. This requires an active database connection, which it will use to resolve constraint names; this means you must @@ -1033,14 +1029,14 @@ generate the SQL against a copy of the database you wish to later apply it on. Note that ``sqlmigrate`` doesn't colorize its output. -The :djadminopt:`--database` option can be used to specify the database for -which to generate the SQL. - .. django-admin-option:: --backwards -By default, the SQL created is for running the migration in the forwards -direction. Pass ``--backwards`` to generate the SQL for -unapplying the migration instead. +Generates the SQL for unapplying the migration. By default, the SQL created is +for running the migration in the forwards direction. + +.. django-admin-option:: --database DATABASE + +Specifies the database for which to generate the SQL. Defaults to ``default``. .. versionchanged:: 1.9 @@ -1048,10 +1044,10 @@ unapplying the migration instead. generated for each migration operation is preceded by the operation's description. -sqlsequencereset ------------------------------------------- +sqlsequencereset +---------------- -.. django-admin:: sqlsequencereset +.. django-admin:: sqlsequencereset app_label [app_label ...] Prints the SQL statements for resetting sequences for the given app name(s). @@ -1061,13 +1057,14 @@ number for automatically incremented fields. Use this command to generate SQL which will fix cases where a sequence is out of sync with its automatically incremented field data. -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. +.. django-admin-option:: --database DATABASE -squashmigrations [] ----------------------------------------------------------------------- +Specifies the database for which to print the SQL. Defaults to ``default``. -.. django-admin:: squashmigrations +squashmigrations +---------------- + +.. django-admin:: squashmigrations app_label [start_migration_name] migration_name Squashes the migrations for ``app_label`` up to and including ``migration_name`` down into fewer migrations, if possible. The resulting squashed migrations @@ -1083,17 +1080,24 @@ squashing limitation of :class:`~django.db.migrations.operations.RunPython` and .. django-admin-option:: --no-optimize -By default, Django will try to optimize the operations in your migrations -to reduce the size of the resulting file. Pass ``--no-optimize`` if this -process is failing for you or creating incorrect migrations, though please -also file a Django bug report about the behavior, as optimization is meant -to be safe. +Disables the optimizer when generating a squashed migration. By default, Django +will try to optimize the operations in your migrations to reduce the size of +the resulting file. Use this option if this process is failing or creating +incorrect migrations, though please also file a Django bug report about the +behavior, as optimization is meant to be safe. +.. django-admin-option:: --noinput, --no-input -startapp [destination] ----------------------------------- +Suppresses all user prompts. -.. django-admin:: startapp +.. versionchanged:: 1.9 + + The ``--no-input`` alias was added. + +startapp +-------- + +.. django-admin:: startapp name [directory] Creates a Django app directory structure for the given app name in the current directory or the given destination. @@ -1113,10 +1117,9 @@ For example:: .. _custom-app-and-project-templates: -.. django-admin-option:: --template +.. django-admin-option:: --template TEMPLATE -With the ``--template`` option, you can use a custom app template by providing -either the path to a directory with the app template file, or a path to a +Provides the path to a directory with a custom app template file or a path to a compressed file (``.tar.gz``, ``.tar.bz2``, ``.tgz``, ``.tbz``, ``.zip``) containing the app template files. @@ -1134,11 +1137,19 @@ zip files, you can use a URL like:: django-admin startapp --template=https://github.com/githubuser/django-app-template/archive/master.zip myapp -When Django copies the app template files, it also renders certain files -through the template engine: the files whose extensions match the -``--extension`` option (``py`` by default) and the files whose names are passed -with the ``--name`` option. The :class:`template context -` used is: +.. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS + +Specifies which file extensions in the app template should be rendered with the +template engine. Defaults to ``py``. + +.. django-admin-option:: --name FILES, -n FILES + +Specifies which files in the app template (in addition to those matching +``--extension``) should be rendered with the template engine. Defaults to an +empty list. + +The :class:`template context ` used for all matching +files is: - Any option passed to the ``startapp`` command (among the command's supported options) @@ -1166,10 +1177,10 @@ with the ``--name`` option. The :class:`template context .. _source: https://github.com/django/django/tree/master/django/conf/app_template/ -startproject [destination] ----------------------------------------- +startproject +------------ -.. django-admin:: startproject +.. django-admin:: startproject name [directory] Creates a Django project directory structure for the given project name in the current directory or the given destination. @@ -1190,30 +1201,23 @@ For example:: django-admin startproject myproject /Users/jezdez/Code/myproject_repo -As with the :djadmin:`startapp` command, the ``--template`` option lets you -specify a directory, file path or URL of a custom project template. See the -:djadmin:`startapp` documentation for details of supported project template -formats. +.. django-admin-option:: --template TEMPLATE -For example, this would look for a project template in the given directory -when creating the ``myproject`` project:: +Specifies a directory, file path, or URL of a custom project template. See the +:option:`startapp --template` documentation for examples and usage. - django-admin startproject --template=/Users/jezdez/Code/my_project_template myproject +.. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS -Django will also accept URLs (``http``, ``https``, ``ftp``) to compressed -archives with the project template files, downloading and extracting them on the -fly. +Specifies which file extensions in the project template should be rendered with +the template engine. Defaults to ``py``. -For example, taking advantage of GitHub's feature to expose repositories as -zip files, you can use a URL like:: +.. django-admin-option:: --name FILES, -n FILES - django-admin startproject --template=https://github.com/githubuser/django-project-template/archive/master.zip myproject +Specifies which files in the project template (in addition to those matching +``--extension``) should be rendered with the template engine. Defaults to an +empty list. -When Django copies the project template files, it also renders certain files -through the template engine: the files whose extensions match the -``--extension`` option (``py`` by default) and the files whose names are passed -with the ``--name`` option. The :class:`template context -` used is: +The :class:`template context ` used is: - Any option passed to the ``startproject`` command (among the command's supported options) @@ -1227,64 +1231,75 @@ for :djadmin:`startapp`. .. _`template source`: https://github.com/django/django/tree/master/django/conf/project_template/ -test ------------------------------ +test +---- -.. django-admin:: test +.. django-admin:: test [test_label [test_label ...]] -Runs tests for all installed models. See :doc:`/topics/testing/index` for more +Runs tests for all installed apps. See :doc:`/topics/testing/index` for more information. .. django-admin-option:: --failfast -The ``--failfast`` option can be used to stop running tests and report the -failure immediately after a test fails. +Stops running tests and reports the failure immediately after a test fails. -.. django-admin-option:: --testrunner +.. django-admin-option:: --testrunner TESTRUNNER -The ``--testrunner`` option can be used to control the test runner class that -is used to execute tests. If this value is provided, it overrides the value -provided by the :setting:`TEST_RUNNER` setting. +Controls the test runner class that is used to execute tests. This value +overrides the value provided by the :setting:`TEST_RUNNER` setting. -.. django-admin-option:: --liveserver +.. django-admin-option:: --liveserver LIVESERVER -The ``--liveserver`` option can be used to override the default address where -the live server (used with :class:`~django.test.LiveServerTestCase`) is -expected to run from. The default value is ``localhost:8081-8179``. +Overrides the default address where the live server (used with +:class:`~django.test.LiveServerTestCase`) is expected to run from. The default +value is ``localhost:8081-8179``. .. versionchanged:: 1.9 In earlier versions, the default value was ``localhost:8081``. -.. django-admin-option:: --keepdb +.. django-admin-option:: --noinput, --no-input -The ``--keepdb`` option can be used to preserve the test database between test -runs. This has the advantage of skipping both the create and destroy actions -which can greatly decrease the time to run tests, especially those in a large -test suite. If the test database does not exist, it will be created on the first -run and then preserved for each subsequent run. Any unapplied migrations will also -be applied to the test database before running the test suite. +Suppresses all user prompts. A typical prompt is a warning about deleting an +existing test database. -.. django-admin-option:: --reverse +.. versionchanged:: 1.9 -The ``--reverse`` option can be used to sort test cases in the opposite order. -This may help in debugging the side effects of tests that aren't properly -isolated. :ref:`Grouping by test class ` is preserved when using -this option. + The ``--no-input`` alias was added. -.. django-admin-option:: --debug-sql +Test runner options +~~~~~~~~~~~~~~~~~~~ -The ``--debug-sql`` option can be used to enable :ref:`SQL logging -` for failing tests. If :djadminopt:`--verbosity` is ``2``, -then queries in passing tests are also output. +The ``test`` command receives options on behalf of the specified +:option:`--testrunner`. These are the options of the default test runner: +:class:`~django.test.runner.DiscoverRunner`. -.. django-admin-option:: --parallel +.. django-admin-option:: --keepdb, -k + +Preserves the test database between test runs. This has the advantage of +skipping both the create and destroy actions which can greatly decrease the +time to run tests, especially those in a large test suite. If the test database +does not exist, it will be created on the first run and then preserved for each +subsequent run. Any unapplied migrations will also be applied to the test +database before running the test suite. + +.. django-admin-option:: --reverse, -r + +Sorts test cases in the opposite execution order. This may help in debugging +the side effects of tests that aren't properly isolated. :ref:`Grouping by test +class ` is preserved when using this option. + +.. django-admin-option:: --debug-sql, -d + +Enables :ref:`SQL logging ` for failing tests. If +``--verbosity`` is ``2``, then queries in passing tests are also output. + +.. django-admin-option:: --parallel [N] .. versionadded:: 1.9 -The ``--parallel`` option can be used to run tests in parallel in separate -processes. Since modern processors have multiple cores, this allows running -tests significantly faster. +Runs tests in separate parallel processes. Since modern processors have +multiple cores, this allows running tests significantly faster. By default ``--parallel`` runs one process per core according to :func:`multiprocessing.cpu_count()`. You can adjust the number of processes @@ -1324,10 +1339,10 @@ don't. in order to exchange them between processes. See :ref:`python:pickle-picklable` for details. -testserver --------------------------------- +testserver +---------- -.. django-admin:: testserver +.. django-admin:: testserver [fixture [fixture ...]] Runs a Django development server (as in :djadmin:`runserver`) using data from the given fixture(s). @@ -1362,12 +1377,11 @@ Note that this server does *not* automatically detect changes to your Python source code (as :djadmin:`runserver` does). It does, however, detect changes to templates. -.. django-admin-option:: --addrport [port number or ipaddr:port] +.. django-admin-option:: --addrport ADDRPORT -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 :djadmin:`runserver` -command. +Specifies 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 :djadmin:`runserver` command. Examples: @@ -1384,8 +1398,14 @@ To run on 1.2.3.4:7000 with a ``test`` fixture:: django-admin testserver --addrport 1.2.3.4:7000 test -The :djadminopt:`--noinput` option may be provided to suppress all user -prompts. +.. django-admin-option:: --noinput, --no-input + +Suppresses all user prompts. A typical prompt is a warning about deleting an +existing test database. + +.. versionchanged:: 1.9 + + The ``--no-input`` alias was added. Commands provided by applications ================================= @@ -1401,7 +1421,7 @@ their application. changepassword ~~~~~~~~~~~~~~ -.. django-admin:: changepassword +.. django-admin:: changepassword [] This command is only available if Django's :doc:`authentication system ` (``django.contrib.auth``) is installed. @@ -1411,8 +1431,9 @@ for the given user. If the entries are identical, this immediately becomes the new password. If you do not supply a user, the command will attempt to change the password whose username matches the current user. -Use the ``--database`` option to specify the database to query for the user. If -it's not supplied, Django will use the ``default`` database. +.. django-admin-option:: --database DATABASE + +Specifies the database to query for the user. Defaults to ``default``. Example usage:: @@ -1435,16 +1456,17 @@ 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 +.. django-admin-option:: --username USERNAME +.. django-admin-option:: --email EMAIL The username and email 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. -Use the ``--database`` option to specify the database into which the superuser -object will be saved. +.. django-admin-option:: --database DATABASE + +Specifies the database into which the superuser object will be saved. You can subclass the management command and override ``get_input_data()`` if you want to customize data input and validation. Consult the source code for @@ -1512,118 +1534,73 @@ Please refer to its :djadmin:`description ` in the :doc:`staticfiles Default options =============== +.. program:: None + Although some commands may allow their own custom options, every command allows for the following options: -.. django-admin-option:: --pythonpath - -Example usage:: - - django-admin migrate --pythonpath='/home/djangoprojects/myproject' +.. django-admin-option:: --pythonpath PYTHONPATH Adds the given filesystem path to the Python `import search path`_. If this isn't provided, ``django-admin`` will use the ``PYTHONPATH`` environment variable. -Note that this option is unnecessary in ``manage.py``, because it takes care of -setting the Python path for you. +This option is unnecessary in ``manage.py``, because it takes care of setting +the Python path for you. + +Example usage:: + + django-admin migrate --pythonpath='/home/djangoprojects/myproject' .. _import search path: http://www.diveintopython.net/getting_to_know_python/everything_is_an_object.html -.. django-admin-option:: --settings +.. django-admin-option:: --settings SETTINGS + +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`` will use the ``DJANGO_SETTINGS_MODULE`` environment variable. + +This option is unnecessary in ``manage.py``, because it uses +``settings.py`` from the current project by default. Example usage:: django-admin migrate --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`` will use the ``DJANGO_SETTINGS_MODULE`` environment -variable. - -Note that this option is unnecessary in ``manage.py``, because it uses -``settings.py`` from the current project by default. - .. django-admin-option:: --traceback +Displays a full stack trace when a :exc:`~django.core.management.CommandError` +is raised. By default, ``django-admin`` will show a simple error message when a +``CommandError`` occurs and a full stack trace for any other exception. + Example usage:: django-admin migrate --traceback -By default, ``django-admin`` will show a simple error message whenever a -:exc:`~django.core.management.CommandError` occurs, but a full stack trace -for any other exception. If you specify ``--traceback``, ``django-admin`` -will also output a full stack trace when a ``CommandError`` is raised. +.. django-admin-option:: --verbosity {0,1,2,3}, --v {0,1,2,3} -.. django-admin-option:: --verbosity - -Example usage:: - - django-admin migrate --verbosity 2 - -Use ``--verbosity`` to specify the amount of notification and debug information -that ``django-admin`` should print to the console. +Specifies the amount of notification and debug information that a command +should print to the console. * ``0`` means no output. * ``1`` means normal output (default). * ``2`` means verbose output. * ``3`` means *very* verbose output. +Example usage:: + + django-admin migrate --verbosity 2 + .. django-admin-option:: --no-color +Disables colorized command output. Some commands format their output to be +colorized. For example, errors will be printed to the console in red and SQL +statements will be syntax highlighted. + Example usage:: django-admin runserver --no-color -By default, ``django-admin`` will format the output to be colorized. For -example, errors will be printed to the console in red and SQL statements will -be syntax highlighted. To prevent this and have a plain text output, pass the -``--no-color`` option when running your command. - -Common options -============== - -The following options are not available on every command, but they are common -to a number of commands. - -.. django-admin-option:: --database - -Used to specify the database on which a command will operate. If not -specified, this option will default to an alias of ``default``. - -For example, to dump data from the database with the alias ``master``:: - - django-admin dumpdata --database=master - -.. django-admin-option:: --exclude - -Exclude a specific application from the applications whose contents is -output. For example, to specifically exclude the ``auth`` application from -the output of dumpdata, you would call:: - - django-admin dumpdata --exclude=auth - -If you want to exclude multiple applications, use multiple ``--exclude`` -directives:: - - django-admin dumpdata --exclude=auth --exclude=contenttypes - -.. django-admin-option:: --locale - -Use the ``--locale`` or ``-l`` option to specify the locale to process. -If not provided all locales are processed. - -.. django-admin-option:: --noinput - -Use the ``--noinput`` option to suppress all user prompting, such as "Are -you sure?" confirmation messages. This is useful if ``django-admin`` is -being executed as an unattended, automated script. You can use ``--no-input`` -as an alias for this option. - -.. versionchanged:: 1.9 - - The ``--no-input`` alias was added. - Extra niceties ============== diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 10c5075919..f627d8a333 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1830,8 +1830,8 @@ When you supply ``None`` as a value for an app, Django will consider the app as an app without migrations regardless of an existing ``migrations`` submodule. This can be used, for example, in a test settings file to skip migrations while testing (tables will still be created for the apps' models). If this is used in -your general project settings, remember to use the migrate -:djadminopt:`--run-syncdb` option if you want to create tables for the app. +your general project settings, remember to use the :option:`migrate +--run-syncdb` option if you want to create tables for the app. .. setting:: MONTH_DAY_FORMAT diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index ca6f9c2de6..a4696a811f 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -389,7 +389,7 @@ Arguments sent with this signal: ``verbosity`` Indicates how much information manage.py is printing on screen. See - the :djadminopt:`--verbosity` flag for details. + the :option:`--verbosity` flag for details. Functions which listen for :data:`pre_migrate` should adjust what they output to the screen based on the value of this argument. @@ -430,7 +430,7 @@ Arguments sent with this signal: ``verbosity`` Indicates how much information manage.py is printing on screen. See - the :djadminopt:`--verbosity` flag for details. + the :option:`--verbosity` flag for details. Functions which listen for :data:`post_migrate` should adjust what they output to the screen based on the value of this argument. diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index ff6900243f..57478ee285 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -219,22 +219,20 @@ Internationalization Management Commands ^^^^^^^^^^^^^^^^^^^ -* The new :djadminopt:`--fail-level` option of the :djadmin:`check` command - allows specifying the message level that will cause the command to exit with - a non-zero status. +* The new :option:`check --fail-level` option allows specifying the message + level that will cause the command to exit with a non-zero status. -* The new :djadminopt:`makemigrations --check <--check>` option makes the - command exit with a non-zero status when model changes without migrations are - detected. +* The new :option:`makemigrations --check` option makes the command exit + with a non-zero status when model changes without migrations are detected. * :djadmin:`makemigrations` now displays the path to the migration files that it generates. -* The :djadmin:`shell` ``--interface`` option now accepts ``python`` to force - use of the "plain" Python interpreter. +* The :option:`shell --interface` option now accepts ``python`` to force use of + the "plain" Python interpreter. -* The new :djadminopt:`shell --command <--command>` option lets you run a - command as Django and exit, instead of opening the interactive shell. +* The new :option:`shell --command` option lets you run a command as Django and + exit, instead of opening the interactive shell. Migrations ^^^^^^^^^^ @@ -510,7 +508,7 @@ Miscellaneous ~~~~~~~~~~~~~ * The ``makemigrations --exit`` option is deprecated in favor of the - :djadminopt:`--check` option. + :option:`makemigrations --check` option. * ``django.utils.functional.allow_lazy()`` is deprecated in favor of the new :func:`~django.utils.functional.keep_lazy` function which can be used with a diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index fa08b717bd..0aedf23ede 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -622,8 +622,7 @@ Django 1.4 also includes several smaller improvements worth noting: This should make it easier to read when debugging interaction with client-side JavaScript. -* Added the :djadminopt:`--no-location` option to the :djadmin:`makemessages` - command. +* Added the :option:`makemessages --no-location` option. * Changed the ``locmem`` cache backend to use ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other @@ -1139,7 +1138,7 @@ Development Server Multithreading ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The development server is now is multithreaded by default. Use the -:djadminopt:`--nothreading` option to disable the use of threading in the +:option:`runserver --nothreading` option to disable the use of threading in the development server:: django-admin.py runserver --nothreading diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index 97e248423c..44f96d248c 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -315,9 +315,8 @@ Django 1.5 also includes several smaller improvements worth noting: whenever a user fails to login successfully. See :data:`~django.contrib.auth.signals.user_login_failed` -* The loaddata management command now supports an - :djadminopt:`--ignorenonexistent` option to ignore data for fields that no - longer exist. +* The new :option:`loaddata --ignorenonexistent` option ignore data for fields + that no longer exist. * :meth:`~django.test.SimpleTestCase.assertXMLEqual` and :meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow @@ -635,7 +634,7 @@ Behavior of ``syncdb`` with multiple databases types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions (when :mod:`~django.contrib.auth` is enabled) should be created in the target database. Previously, it created them in the default database, even when -another database was specified with the :djadminopt:`--database` option. +another database was specified with the ``--database`` option. If you use ``syncdb`` on multiple databases, you should ensure that your routers allow synchronizing content types and permissions to only one of diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 6e03178620..bb24f60969 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -287,9 +287,8 @@ Minor features and :func:`~django.contrib.auth.views.password_change`, you can now pass URL names and they will be resolved. -* The :djadmin:`dumpdata` ``manage.py`` command now has a :djadminopt:`--pks` - option which will allow users to specify the primary keys of objects they - want to dump. This option can only be used with one model. +* The new :option:`dumpdata --pks` option specifies the primary keys of objects + to dump. This option can only be used with one model. * Added ``QuerySet`` methods :meth:`~django.db.models.query.QuerySet.first` and :meth:`~django.db.models.query.QuerySet.last` which are convenience @@ -905,7 +904,7 @@ Miscellaneous * If a ``NoReverseMatch`` exception is raised from a method when rendering a template, it is not silenced. For example, ``{{ obj.view_href }}`` will - cause template rendering to fail if ``view_href()`` raises + cause template rendering to fail if ``view_href()`` raises ``NoReverseMatch``. There is no change to the :ttag:`{% url %}` tag, it causes template rendering to fail like always when ``NoReverseMatch`` is raised. @@ -946,9 +945,8 @@ Miscellaneous * :meth:`~django.core.validators.validate_email` now accepts email addresses with ``localhost`` as the domain. -* The :djadminopt:`--keep-pot` option was added to :djadmin:`makemessages` - to prevent django from deleting the temporary .pot file it generates before - creating the .po file. +* The new :option:`makemessages --keep-pot` option prevents deleting the + temporary .pot file generated before creating the .po file. * The undocumented ``django.core.servers.basehttp.WSGIServerException`` has been removed. Use ``socket.error`` provided by the standard library instead. diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index fc09f5f99d..005882afe6 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -698,16 +698,16 @@ Internationalization Management Commands ^^^^^^^^^^^^^^^^^^^ -* The :djadminopt:`--no-color` option for ``django-admin`` allows you to - disable the colorization of management command output. +* The new :option:`--no-color` option for ``django-admin`` disables the + colorization of management command output. -* The new :djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary` - options for :djadmin:`dumpdata`, and the new ``use_natural_foreign_keys`` and +* The new :option:`dumpdata --natural-foreign` and :option:`dumpdata + --natural-primary` options, and the new ``use_natural_foreign_keys`` and ``use_natural_primary_keys`` arguments for ``serializers.serialize()``, allow the use of natural primary keys when serializing. * It is no longer necessary to provide the cache table name or the - :djadminopt:`--database` option for the :djadmin:`createcachetable` command. + ``--database`` option for the :djadmin:`createcachetable` command. Django takes this information from your settings file. If you have configured multiple caches or multiple databases, all cache tables are created. @@ -1444,8 +1444,8 @@ Miscellaneous * The ``sql*`` management commands now respect the ``allow_migrate()`` method of :setting:`DATABASE_ROUTERS`. If you have models synced to non-default - databases, use the :djadminopt:`--database` flag to get SQL for those - models (previously they would always be included in the output). + databases, use the ``--database`` flag to get SQL for those models + (previously they would always be included in the output). * Decoding the query string from URLs now falls back to the ISO-8859-1 encoding when the input is not valid UTF-8. @@ -1624,7 +1624,7 @@ Natural key serialization options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` have been -deprecated. Use :djadminopt:`--natural-foreign` instead. +deprecated. Use :option:`dumpdata --natural-foreign` instead. Similarly, the ``use_natural_keys`` argument for ``serializers.serialize()`` has been deprecated. Use ``use_natural_foreign_keys`` instead. diff --git a/docs/releases/1.8.1.txt b/docs/releases/1.8.1.txt index b01b09e081..09b602c5c4 100644 --- a/docs/releases/1.8.1.txt +++ b/docs/releases/1.8.1.txt @@ -75,7 +75,7 @@ Bugfixes * Fixed a migration crash when renaming the target model of a many-to-many relation (:ticket:`24725`). -* Removed flushing of the test database with :djadminopt:`--keepdb`, which +* Removed flushing of the test database with :option:`test --keepdb`, which prevented apps with data migrations from using the option (:ticket:`24729`). * Fixed ``makemessages`` crash in some locales (:ticket:`23271`). diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index 7f165ad1a9..d75250082e 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -68,9 +68,8 @@ Security enhancements Several features of the django-secure_ third-party library have been integrated into Django. :class:`django.middleware.security.SecurityMiddleware` provides several security enhancements to the request/response cycle. The new -:djadminopt:`--deploy` option of the :djadmin:`check` command allows you to -check your production settings file for ways to increase the security of your -site. +:option:`check --deploy` option allows you to check your production settings +file for ways to increase the security of your site. .. _django-secure: https://pypi.python.org/pypi/django-secure @@ -410,18 +409,17 @@ Management Commands * Commands from alternate package formats like eggs are now also discovered. -* :djadmin:`dumpdata` now has the option :djadminopt:`--output` which allows - specifying the file to which the serialized data is written. +* The new :option:`dumpdata --output` option allows specifying a file to which + the serialized data is written. -* :djadmin:`makemessages` and :djadmin:`compilemessages` now have the option - :djadminopt:`--exclude` which allows exclusion of specific locales from - processing. +* The new :option:`makemessages --exclude` and :option:`compilemessages + --exclude` options allow excluding specific locales from processing. * :djadmin:`compilemessages` now has a ``--use-fuzzy`` or ``-f`` option which includes fuzzy translations into compiled files. -* The :djadminopt:`--ignorenonexistent` option of the :djadmin:`loaddata` - management command now ignores data for models that no longer exist. +* The :option:`loaddata --ignorenonexistent` option now ignores data for models + that no longer exist. * :djadmin:`runserver` now uses daemon threads for faster reloading. @@ -439,15 +437,15 @@ Management Commands * The :djadmin:`dbshell` command now supports MySQL's optional SSL certificate authority setting (``--ssl-ca``). -* The :djadminopt:`--name` option for :djadmin:`makemigrations` allows you to - to give the migration(s) a custom name instead of a generated one. +* The new :option:`makemigrations --name` allows giving the migration(s) a + custom name instead of a generated one. * The :djadmin:`loaddata` command now prevents repeated fixture loading. If :setting:`FIXTURE_DIRS` contains duplicates or a default fixture directory path (``app_name/fixtures``), an exception is raised. -* :djadmin:`makemigrations` now supports an :djadminopt:`--exit` option to - exit with an error code if no migrations are created. +* The new :option:`makemigrations --exit` option allows exiting with an error + code if no migrations are created. * The new :djadmin:`showmigrations` command allows listing all migrations and their dependencies in a project. @@ -637,9 +635,9 @@ Tests allows you to test that two JSON fragments are not equal. * Added options to the :djadmin:`test` command to preserve the test database - (:djadminopt:`--keepdb`), to run the test cases in reverse order - (:djadminopt:`--reverse`), and to enable SQL logging for failing tests - (:djadminopt:`--debug-sql`). + (:option:`--keepdb `), to run the test cases in reverse order + (:option:`--reverse `), and to enable SQL logging for failing + tests (:option:`--debug-sql `). * Added the :attr:`~django.test.Response.resolver_match` attribute to test client responses. @@ -1189,10 +1187,9 @@ Miscellaneous ``name`` column won't be dropped from the database. Use ``migrate.py migrate --fake-initial`` to fake only the initial migration instead. -* :djadmin:`migrate` now accepts the :djadminopt:`--fake-initial` option to - allow faking initial migrations. In 1.7 initial migrations were always - automatically faked if all tables created in an initial migration already - existed. +* The new :option:`migrate --fake-initial` option allows faking initial + migrations. In 1.7, initial migrations were always automatically faked if all + tables created in an initial migration already existed. * An app *without* migrations with a ``ForeignKey`` to an app *with* migrations may now result in a foreign key constraint error when migrating the database diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt index 35c673b4f1..a74798b928 100644 --- a/docs/releases/1.9.txt +++ b/docs/releases/1.9.txt @@ -131,8 +131,8 @@ degradation. Running tests in parallel ~~~~~~~~~~~~~~~~~~~~~~~~~ -The :djadmin:`test` command now supports a :djadminopt:`--parallel` option to -run a project's tests in multiple processes in parallel. +The :djadmin:`test` command now supports a :option:`--parallel ` option to run a project's tests in multiple processes in parallel. Each process gets its own database. You must ensure that different test cases don't access the same resources. For instance, test cases that touch the @@ -451,8 +451,7 @@ Migrations * Initial migrations are now marked with an :attr:`initial = True ` class attribute which allows - :djadminopt:`migrate --fake-initial <--fake-initial>` to more easily detect - initial migrations. + :option:`migrate --fake-initial` to more easily detect initial migrations. * Added support for serialization of ``functools.partial`` and ``LazyObject`` instances. @@ -1407,8 +1406,8 @@ removed in Django 1.9 (please see the :ref:`deprecation timeline * Support for ``allow_syncdb`` on database routers is removed. * Automatic syncing of apps without migrations is removed. Migrations are - compulsory for all apps unless you pass the :djadminopt:`--run-syncdb` - option to ``migrate``. + compulsory for all apps unless you pass the :option:`migrate --run-syncdb` + option. * The SQL management commands for apps without migrations, ``sql``, ``sqlall``, ``sqlclear``, ``sqldropindexes``, and ``sqlindexes``, are removed. diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index e0740a201d..e59f0318cc 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -70,8 +70,9 @@ Create superusers using the :djadmin:`createsuperuser` command:: $ python manage.py createsuperuser --username=joe --email=joe@example.com You will be prompted for a password. After you enter one, the user will be -created immediately. If you leave off the :djadminopt:`--username` or the -:djadminopt:`--email` options, it will prompt you for those values. +created immediately. If you leave off the :option:`--username ` or :option:`--email ` options, it will +prompt you for those values. Changing passwords ------------------ diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 1a860a71e3..fc0d81abe1 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -216,7 +216,7 @@ Like :djadmin:`migrate`, :djadmin:`createcachetable` won't touch an existing table. It will only create missing tables. To print the SQL that would be run, rather than run it, use the -:djadminopt:`--dry-run` option. +:option:`createcachetable --dry-run` option. Multiple databases ~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/checks.txt b/docs/topics/checks.txt index 5521c9cb8d..b0074891db 100644 --- a/docs/topics/checks.txt +++ b/docs/topics/checks.txt @@ -106,8 +106,7 @@ settings file like this:: def my_check(app_configs, **kwargs): ... -These checks will only be run if the :djadminopt:`--deploy` option is passed to -the :djadmin:`check` command. +These checks will only be run if the :option:`check --deploy` option is used. You can also use ``register`` as a function rather than a decorator by passing a callable object (usually a function) as the first argument diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index f4b6367033..ca35d1f933 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -76,7 +76,7 @@ Synchronizing your databases The :djadmin:`migrate` management command operates on one database at a time. By default, it operates on the ``default`` database, but by -providing a :djadminopt:`--database` argument, you can tell :djadmin:`migrate` +providing the :option:`--database ` option, you can tell it to synchronize a different database. So, to synchronize all models onto all databases in our example, you would need to call:: @@ -91,10 +91,9 @@ constraining the availability of particular models. Using other management commands ------------------------------- -The other ``django-admin`` commands that interact with the database -operate in the same way as :djadmin:`migrate` -- they only ever operate -on one database at a time, using :djadminopt:`--database` to control -the database used. +The other ``django-admin`` commands that interact with the database operate in +the same way as :djadmin:`migrate` -- they only ever operate on one database at +a time, using ``--database`` to control the database used. .. _topics-db-multi-db-routing: diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index 01b5404fd6..b5e706a9b9 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -143,7 +143,7 @@ get both the changes to your models and the accompanying migration at the same time. If you want to give the migration(s) a meaningful name instead of a generated -one, you can use the :djadminopt:`--name` option:: +one, you can use the :option:`makemigrations --name` option:: $ python manage.py makemigrations --name changed_my_model your_app_label @@ -291,15 +291,14 @@ migration class. If an ``initial`` class attribute isn't found, a migration will be considered "initial" if it is the first migration in the app (i.e. if it has no dependencies on any other migration in the same app). -When :djadmin:`migrate` is run with the :djadminopt:`--fake-initial` option, -these initial migrations are treated specially. For an initial migration that -creates one or more tables (``CreateModel`` operation), Django checks that all -of those tables already exist in the database and fake-applies the migration -if so. Similarly, for an initial migration that adds one or more fields -(``AddField`` operation), Django checks that all of the respective columns -already exist in the database and fake-applies the migration if so. Without -:djadminopt:`--fake-initial`, initial migrations are treated no differently -from any other migration. +When the :option:`migrate --fake-initial` option is used, these initial +migrations are treated specially. For an initial migration that creates one or +more tables (``CreateModel`` operation), Django checks that all of those tables +already exist in the database and fake-applies the migration if so. Similarly, +for an initial migration that adds one or more fields (``AddField`` operation), +Django checks that all of the respective columns already exist in the database +and fake-applies the migration if so. Without ``--fake-initial``, initial +migrations are treated no differently from any other migration. Adding migrations to apps ------------------------- @@ -317,9 +316,9 @@ need to convert it to use migrations; this is a simple process:: This will make a new initial migration for your app. Now, run ``python manage.py migrate --fake-initial``, and Django will detect that you have an initial migration *and* that the tables it wants to create already exist, and -will mark the migration as already applied. (Without the -:djadminopt:`--fake-initial` flag, the :djadmin:`migrate` command would error -out because the tables it wants to create already exist.) +will mark the migration as already applied. (Without the :option:`migrate +--fake-initial` flag, the command would error out because the tables it wants +to create already exist.) Note that this only works given two things: diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index 2221463210..ec80efafc0 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -471,8 +471,8 @@ already in use, and do not need to ensure that deserialized objects retain the same primary keys. If you are using :djadmin:`dumpdata` to generate serialized data, use the -:djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary` command -line flags to generate natural keys. +:option:`dumpdata --natural-foreign` and :option:`dumpdata --natural-primary` +command line flags to generate natural keys. .. note:: @@ -495,7 +495,7 @@ a "forward reference" with natural keys -- the data you're referencing must exist before you include a natural key reference to that data. To accommodate this limitation, calls to :djadmin:`dumpdata` that use -the :djadminopt:`--natural-foreign` option will serialize any model with a +the :option:`dumpdata --natural-foreign` option will serialize any model with a ``natural_key()`` method before serializing standard primary key objects. However, this may not always be enough. If your natural key refers to diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 8f01f0c8a8..1674a40a39 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -115,9 +115,10 @@ wait for the currently running test to complete and then exit gracefully. During a graceful exit the test runner will output details of any test failures, report on how many tests were run and how many errors and failures were encountered, and destroy any test databases as usual. Thus pressing -``Ctrl-C`` can be very useful if you forget to pass the :djadminopt:`--failfast` -option, notice that some tests are unexpectedly failing, and want to get details -on the failures without waiting for the full test run to complete. +``Ctrl-C`` can be very useful if you forget to pass the :option:`--failfast +` option, notice that some tests are unexpectedly failing and +want to get details on the failures without waiting for the full test run to +complete. If you do not want to wait for the currently running test to finish, you can press ``Ctrl-C`` a second time and the test run will halt immediately, @@ -145,10 +146,10 @@ Tests that require a database (namely, model tests) will not use your "real" Regardless of whether the tests pass or fail, the test databases are destroyed when all the tests have been executed. -You can prevent the test databases from being destroyed by adding the -:djadminopt:`--keepdb` flag to the test command. This will preserve the test -database between runs. If the database does not exist, it will first be -created. Any migrations will also be applied in order to keep it p to date. +You can prevent the test databases from being destroyed by using the +:option:`test --keepdb` option. This will preserve the test database between +runs. If the database does not exist, it will first be created. Any migrations +will also be applied in order to keep it p to date. The default test database names are created by prepending ``test_`` to the value of each :setting:`NAME` in :setting:`DATABASES`. When using SQLite, the @@ -221,9 +222,9 @@ the Django test runner reorders tests in the following way: database by a given :class:`~django.test.TransactionTestCase` test, they must be updated to be able to run independently. -You may reverse the execution order inside groups by passing -:djadminopt:`--reverse` to the test command. This can help with ensuring your -tests are independent from each other. +You may reverse the execution order inside groups using the :option:`test +--reverse` option. This can help with ensuring your tests are independent from +each other. .. _test-case-serialized-rollback: diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index e6e8fe52e9..9c50aa0f9f 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -833,9 +833,8 @@ available port in the ``8081-8179`` range. Its full URL can be accessed with In earlier versions, the live server's default address was always ``'localhost:8081'``. -If you'd like to select another address then you may pass a different one to -the :djadmin:`test` command via the :djadminopt:`--liveserver` option, for -example: +If you'd like to select another address, you may pass a different one using the +:option:`test --liveserver` option, for example: .. code-block:: console