test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fixed #23868 -- Added support for non-unique django-admin-options in docs. 

Also documented missing short command line options to fix #24134. This bumps
the minimum sphinx version required to build the docs to 1.3.4.

Thanks Simon Charette for review.
This commit is contained in:
Tim Graham 2016-01-11 20:59:34 -05:00
parent fd1c5bb041
commit e519aab43a
31 changed files with 543 additions and 616 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
django/core/management/commands/showmigrations.py
View File

@ -10,7 +10,7 @@ class Command(BaseCommand):
help = "Shows all available migrations for the current project" help = "Shows all available migrations for the current project"
def add_arguments(self, parser): 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.') help='App labels of applications to limit the output to.')
parser.add_argument('--database', action='store', dest='database', default=DEFAULT_DB_ALIAS, parser.add_argument('--database', action='store', dest='database', default=DEFAULT_DB_ALIAS,
help='Nominates a database to synchronize. Defaults to the "default" database.') help='Nominates a database to synchronize. Defaults to the "default" database.')
@ -33,7 +33,7 @@ class Command(BaseCommand):
if options['format'] == "plan": if options['format'] == "plan":
return self.show_plan(connection) return self.show_plan(connection)
else: 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): def show_list(self, connection, app_names=None):
""" """

41
docs/_ext/djangodocs.py
View File

@ -9,6 +9,7 @@ from docutils import nodes
from docutils.parsers.rst import directives from docutils.parsers.rst import directives
from sphinx import addnodes from sphinx import addnodes
from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.domains.std import Cmdoption
from sphinx.util.compat import Directive from sphinx.util.compat import Directive
from sphinx.util.console import bold from sphinx.util.console import bold
from sphinx.util.nodes import set_source_info from sphinx.util.nodes import set_source_info
@ -46,12 +47,7 @@ def setup(app):
indextemplate="pair: %s; django-admin command", indextemplate="pair: %s; django-admin command",
parse_node=parse_django_admin_node, parse_node=parse_django_admin_node,
) )
app.add_description_unit( app.add_directive('django-admin-option', Cmdoption)
directivename="django-admin-option",
rolename="djadminopt",
indextemplate="pair: %s; django-admin command-line option",
parse_node=parse_django_adminopt_node,
)
app.add_config_value('django_next_version', '0.0', True) app.add_config_value('django_next_version', '0.0', True)
app.add_directive('versionadded', VersionDirective) app.add_directive('versionadded', VersionDirective)
app.add_directive('versionchanged', VersionDirective) app.add_directive('versionchanged', VersionDirective)
@ -295,39 +291,10 @@ class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
def parse_django_admin_node(env, sig, signode): def parse_django_admin_node(env, sig, signode):
command = sig.split(' ')[0] command = sig.split(' ')[0]
env._django_curr_admin_command = command env.ref_context['std:program'] = command
title = "django-admin %s" % sig title = "django-admin %s" % sig
signode += addnodes.desc_name(title, title) signode += addnodes.desc_name(title, title)
return sig return command
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
class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder): class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):

2
docs/conf.py
View File

@ -27,7 +27,7 @@ sys.path.append(abspath(join(dirname(__file__), "_ext")))
# -- General configuration ----------------------------------------------------- # -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here. # 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 # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

9
docs/howto/custom-management-commands.txt
View File

@ -123,8 +123,8 @@ parameter of the handle method. See the :py:mod:`argparse` Python documentation
for more about ``add_argument`` usage. for more about ``add_argument`` usage.
In addition to being able to add custom command line options, all In addition to being able to add custom command line options, all
:doc:`management commands</ref/django-admin>` can accept some :doc:`management commands</ref/django-admin>` can accept some default options
default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`. such as :option:`--verbosity` and :option:`--traceback`.
.. _management-commands-and-locales: .. _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 see the available styles (use uppercased versions of the "roles" described
in that section). in that section).
If you pass the :djadminopt:`--no-color` option when running your If you pass the :option:`--no-color` option when running your command, all
command, all ``self.style()`` calls will return the original string ``self.style()`` calls will return the original string uncolored.
uncolored.
Methods Methods
------- -------

7
docs/howto/deployment/checklist.txt
View File

@ -32,10 +32,9 @@ module for production.
Run ``manage.py check --deploy`` Run ``manage.py check --deploy``
================================ ================================
Some of the checks described below can be automated using the Some of the checks described below can be automated using the :option:`check
:djadminopt:`--deploy` option of the :djadmin:`check` command. Be sure to run it --deploy` option. Be sure to run it against your production settings file as
against your production settings file as described in the option's described in the option's documentation.
documentation.
Critical settings Critical settings
================= =================

3
docs/internals/contributing/writing-documentation.txt
View File

@ -241,7 +241,8 @@ __ http://sphinx-doc.org/markup/
.. django-admin-option:: --traceback .. 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):: * Links to Trac tickets (typically reserved for patch release notes)::

3
docs/internals/deprecation.txt
View File

@ -372,10 +372,9 @@ details on these changes.
``get_backend_timeout()`` will be removed. ``get_backend_timeout()`` will be removed.
* The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` 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 * 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. * Private API ``django.forms.forms.get_declared_fields()`` will be removed.

5
docs/ref/checks.txt
View File

@ -69,6 +69,8 @@ class name.
Builtin checks Builtin checks
============== ==============
.. _system-check-builtin-tags:
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 :setting:`SECURE_SSL_REDIRECT`. Use :setting:`SILENCED_SYSTEM_CHECKS` to
silence unneeded checks. silence unneeded checks.
The following checks will be run if you use the :djadminopt:`--deploy` option The following checks are run if you use the :option:`check --deploy` option:
of the :djadmin:`check` command:
* **security.W001**: You do not have * **security.W001**: You do not have
:class:`django.middleware.security.SecurityMiddleware` in your :class:`django.middleware.security.SecurityMiddleware` in your

3
docs/ref/contrib/contenttypes.txt
View File

@ -320,8 +320,7 @@ model:
generic relations, you should probably be using a natural key to uniquely generic relations, you should probably be using a natural key to uniquely
identify related :class:`~django.contrib.contenttypes.models.ContentType` identify related :class:`~django.contrib.contenttypes.models.ContentType`
objects. See :ref:`natural keys<topics-serialization-natural-keys>` and objects. See :ref:`natural keys<topics-serialization-natural-keys>` and
:djadminopt:`dumpdata --natural-foreign <--natural-foreign>` for more :option:`dumpdata --natural-foreign` for more information.
information.
This will enable an API similar to the one used for a normal This will enable an API similar to the one used for a normal
:class:`~django.db.models.ForeignKey`; :class:`~django.db.models.ForeignKey`;

20
docs/ref/contrib/gis/commands.txt
View File

@ -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 The overridden command is spatially-aware, and places geometry fields in the
auto-generated model definition, where appropriate. auto-generated model definition, where appropriate.
ogrinspect <data_source> <model_name> ogrinspect
===================================== ==========
.. django-admin:: ogrinspect .. django-admin:: ogrinspect data_source model_name
The ``ogrinspect`` management command will inspect the given OGR-compatible The ``ogrinspect`` management command will inspect the given OGR-compatible
:class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will :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 output a GeoDjango model with the given model name. There's a detailed example
of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
.. django-admin-option:: --blank <blank_field(s)> .. django-admin-option:: --blank BLANK
Use a comma separated list of OGR field names to add the ``blank=True`` 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 keyword option to the field definition. Set with ``true`` to apply
to all applicable fields. to all applicable fields.
.. django-admin-option:: --decimal <decimal_field(s)> .. django-admin-option:: --decimal DECIMAL
Use a comma separated list of OGR float fields to generate Use a comma separated list of OGR float fields to generate
:class:`~django.db.models.DecimalField` instead of the default :class:`~django.db.models.DecimalField` instead of the default
:class:`~django.db.models.FloatField`. Set to ``true`` to apply to all :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all
OGR float fields. OGR float fields.
.. django-admin-option:: --geom-name <name> .. django-admin-option:: --geom-name GEOM_NAME
Specifies the model attribute name to use for the geometry field. Specifies the model attribute name to use for the geometry field.
Defaults to ``'geom'``. Defaults to ``'geom'``.
.. django-admin-option:: --layer <layer> .. django-admin-option:: --layer LAYER_KEY
The key for specifying which layer in the OGR The key for specifying which layer in the OGR
:class:`~django.contrib.gis.gdal.DataSource` source to use. :class:`~django.contrib.gis.gdal.DataSource` source to use.
@ -61,7 +61,7 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
in the generated model rather than in the generated model rather than
:class:`~django.contrib.gis.db.models.PolygonField`. :class:`~django.contrib.gis.db.models.PolygonField`.
.. django-admin-option:: --name-field <name_field> .. django-admin-option:: --name-field NAME_FIELD
Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model
that will return the given field name. that will return the given field name.
@ -70,13 +70,13 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
Suppresses the ``from django.contrib.gis.db import models`` import statement. Suppresses the ``from django.contrib.gis.db import models`` import statement.
.. django-admin-option:: --null <null_field(s)> .. django-admin-option:: --null NULL
Use a comma separated list of OGR field names to add the ``null=True`` 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 keyword option to the field definition. Set with ``true`` to apply to
all applicable fields. 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 The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts
to automatically determine of the SRID of the data source. to automatically determine of the SRID of the data source.

2
docs/ref/contrib/sitemaps.txt
View File

@ -519,7 +519,7 @@ each time you call ``save()``.
Pinging Google via ``manage.py`` 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 Once the sitemaps application is added to your project, you may also
ping Google using the ``ping_google`` management command:: ping Google using the ``ping_google`` management command::

35
docs/ref/contrib/staticfiles.txt
View File

@ -49,8 +49,8 @@ can help show you which files are found.
On subsequent ``collectstatic`` runs (if ``STATIC_ROOT`` isn't empty), files 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 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 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` :setting:`INSTALLED_APPS`, it's a good idea to use the :option:`collectstatic
option in order to remove stale static files. --clear` option in order to remove stale static files.
Files are searched by using the :setting:`enabled finders Files are searched by using the :setting:`enabled finders
<STATICFILES_FINDERS>`. The default is to look in all locations defined in <STATICFILES_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: 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`` Do NOT prompt the user for input of any kind.
as an alias for this option.
.. versionchanged:: 1.9 .. versionchanged:: 1.9
The ``--no-input`` alias was added. The ``--no-input`` alias was added.
.. django-admin-option:: -i <pattern> .. django-admin-option:: --ignore PATTERN, -i PATTERN
.. django-admin-option:: --ignore <pattern>
Ignore files or directories matching this glob-style pattern. Use multiple Ignore files or directories matching this glob-style pattern. Use multiple
times to ignore more. times to ignore more.
.. django-admin-option:: -n .. django-admin-option:: --dry-run, -n
.. django-admin-option:: --dry-run
Do everything except modify the filesystem. Do everything except modify the filesystem.
.. django-admin-option:: -c .. django-admin-option:: --clear, -c
.. django-admin-option:: --clear
Clear the existing files before trying to copy or link the original file. Clear the existing files before trying to copy or link the original file.
.. django-admin-option:: -l .. django-admin-option:: --link, -l
.. django-admin-option:: --link
Create a symbolic link to each file instead of copying. 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 findstatic
---------- ----------
.. django-admin:: findstatic .. django-admin:: findstatic static file [static file ...]
Searches for one or more relative paths with the enabled finders. Searches for one or more relative paths with the enabled finders.
@ -149,6 +144,8 @@ For example::
Found 'admin/js/core.js' here: Found 'admin/js/core.js' here:
/home/polls.com/src/django/contrib/admin/media/js/core.js /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 By default, all matching locations are found. To only return the first match
for each relative path, use the ``--first`` option:: 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 This is a debugging aid; it'll show you exactly which static file will be
collected for a given path. collected for a given path.
By setting the :djadminopt:`--verbosity` flag to 0, you can suppress the extra By setting the ``--verbosity`` flag to 0, you can suppress the extra output and
output and just get the path names:: just get the path names::
$ python manage.py findstatic css/base.css --verbosity 0 $ python manage.py findstatic css/base.css --verbosity 0
/home/special.polls.com/core/static/css/base.css /home/special.polls.com/core/static/css/base.css
/home/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 On the other hand, by setting the ``--verbosity`` flag to 2, you can get all
get all the directories which were searched:: the directories which were searched::
$ python manage.py findstatic css/base.css --verbosity 2 $ python manage.py findstatic css/base.css --verbosity 2
Found 'css/base.css' here: Found 'css/base.css' here:
@ -183,7 +180,7 @@ get all the directories which were searched::
runserver runserver
--------- ---------
.. django-admin:: runserver .. django-admin:: runserver [addrport]
Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static

829
docs/ref/django-admin.txt
View File

File diff suppressed because it is too large Load Diff

4
docs/ref/settings.txt
View File

@ -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. 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 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 testing (tables will still be created for the apps' models). If this is used in
your general project settings, remember to use the migrate your general project settings, remember to use the :option:`migrate
:djadminopt:`--run-syncdb` option if you want to create tables for the app. --run-syncdb` option if you want to create tables for the app.
.. setting:: MONTH_DAY_FORMAT .. setting:: MONTH_DAY_FORMAT

4
docs/ref/signals.txt
View File

@ -389,7 +389,7 @@ Arguments sent with this signal:
``verbosity`` ``verbosity``
Indicates how much information manage.py is printing on screen. See 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 Functions which listen for :data:`pre_migrate` should adjust what they
output to the screen based on the value of this argument. output to the screen based on the value of this argument.
@ -430,7 +430,7 @@ Arguments sent with this signal:
``verbosity`` ``verbosity``
Indicates how much information manage.py is printing on screen. See 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 Functions which listen for :data:`post_migrate` should adjust what they
output to the screen based on the value of this argument. output to the screen based on the value of this argument.

20
docs/releases/1.10.txt
View File

@ -219,22 +219,20 @@ Internationalization
Management Commands Management Commands
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
* The new :djadminopt:`--fail-level` option of the :djadmin:`check` command * The new :option:`check --fail-level` option allows specifying the message
allows specifying the message level that will cause the command to exit with level that will cause the command to exit with a non-zero status.
a non-zero status.
* The new :djadminopt:`makemigrations --check <--check>` option makes the * The new :option:`makemigrations --check` option makes the command exit
command exit with a non-zero status when model changes without migrations are with a non-zero status when model changes without migrations are detected.
detected.
* :djadmin:`makemigrations` now displays the path to the migration files that * :djadmin:`makemigrations` now displays the path to the migration files that
it generates. it generates.
* The :djadmin:`shell` ``--interface`` option now accepts ``python`` to force * The :option:`shell --interface` option now accepts ``python`` to force use of
use of the "plain" Python interpreter. the "plain" Python interpreter.
* The new :djadminopt:`shell --command <--command>` option lets you run a * The new :option:`shell --command` option lets you run a command as Django and
command as Django and exit, instead of opening the interactive shell. exit, instead of opening the interactive shell.
Migrations Migrations
^^^^^^^^^^ ^^^^^^^^^^
@ -510,7 +508,7 @@ Miscellaneous
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
* The ``makemigrations --exit`` option is deprecated in favor of the * 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 * ``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 :func:`~django.utils.functional.keep_lazy` function which can be used with a

5
docs/releases/1.4.txt
View File

@ -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 This should make it easier to read when debugging interaction with
client-side JavaScript. client-side JavaScript.
* Added the :djadminopt:`--no-location` option to the :djadmin:`makemessages` * Added the :option:`makemessages --no-location` option.
command.
* Changed the ``locmem`` cache backend to use * Changed the ``locmem`` cache backend to use
``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other ``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 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:: development server::
django-admin.py runserver --nothreading django-admin.py runserver --nothreading

7
docs/releases/1.5.txt
View File

@ -315,9 +315,8 @@ Django 1.5 also includes several smaller improvements worth noting:
whenever a user fails to login successfully. See whenever a user fails to login successfully. See
:data:`~django.contrib.auth.signals.user_login_failed` :data:`~django.contrib.auth.signals.user_login_failed`
* The loaddata management command now supports an * The new :option:`loaddata --ignorenonexistent` option ignore data for fields
:djadminopt:`--ignorenonexistent` option to ignore data for fields that no that no longer exist.
longer exist.
* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and * :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
:meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow :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 types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions
(when :mod:`~django.contrib.auth` is enabled) should be created in the target (when :mod:`~django.contrib.auth` is enabled) should be created in the target
database. Previously, it created them in the default database, even when 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 If you use ``syncdb`` on multiple databases, you should ensure that
your routers allow synchronizing content types and permissions to only one of your routers allow synchronizing content types and permissions to only one of

10
docs/releases/1.6.txt
View File

@ -287,9 +287,8 @@ Minor features
and :func:`~django.contrib.auth.views.password_change`, you can now pass and :func:`~django.contrib.auth.views.password_change`, you can now pass
URL names and they will be resolved. URL names and they will be resolved.
* The :djadmin:`dumpdata` ``manage.py`` command now has a :djadminopt:`--pks` * The new :option:`dumpdata --pks` option specifies the primary keys of objects
option which will allow users to specify the primary keys of objects they to dump. This option can only be used with one model.
want to dump. This option can only be used with one model.
* Added ``QuerySet`` methods :meth:`~django.db.models.query.QuerySet.first` * Added ``QuerySet`` methods :meth:`~django.db.models.query.QuerySet.first`
and :meth:`~django.db.models.query.QuerySet.last` which are convenience and :meth:`~django.db.models.query.QuerySet.last` which are convenience
@ -946,9 +945,8 @@ Miscellaneous
* :meth:`~django.core.validators.validate_email` now accepts email addresses * :meth:`~django.core.validators.validate_email` now accepts email addresses
with ``localhost`` as the domain. with ``localhost`` as the domain.
* The :djadminopt:`--keep-pot` option was added to :djadmin:`makemessages` * The new :option:`makemessages --keep-pot` option prevents deleting the
to prevent django from deleting the temporary .pot file it generates before temporary .pot file generated before creating the .po file.
creating the .po file.
* The undocumented ``django.core.servers.basehttp.WSGIServerException`` has * The undocumented ``django.core.servers.basehttp.WSGIServerException`` has
been removed. Use ``socket.error`` provided by the standard library instead. been removed. Use ``socket.error`` provided by the standard library instead.

16
docs/releases/1.7.txt
View File

@ -698,16 +698,16 @@ Internationalization
Management Commands Management Commands
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
* The :djadminopt:`--no-color` option for ``django-admin`` allows you to * The new :option:`--no-color` option for ``django-admin`` disables the
disable the colorization of management command output. colorization of management command output.
* The new :djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary` * The new :option:`dumpdata --natural-foreign` and :option:`dumpdata
options for :djadmin:`dumpdata`, and the new ``use_natural_foreign_keys`` and --natural-primary` options, and the new ``use_natural_foreign_keys`` and
``use_natural_primary_keys`` arguments for ``serializers.serialize()``, allow ``use_natural_primary_keys`` arguments for ``serializers.serialize()``, allow
the use of natural primary keys when serializing. the use of natural primary keys when serializing.
* It is no longer necessary to provide the cache table name or the * 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 Django takes this information from your settings file. If you have configured
multiple caches or multiple databases, all cache tables are created. 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 * The ``sql*`` management commands now respect the ``allow_migrate()`` method
of :setting:`DATABASE_ROUTERS`. If you have models synced to non-default of :setting:`DATABASE_ROUTERS`. If you have models synced to non-default
databases, use the :djadminopt:`--database` flag to get SQL for those databases, use the ``--database`` flag to get SQL for those models
models (previously they would always be included in the output). (previously they would always be included in the output).
* Decoding the query string from URLs now falls back to the ISO-8859-1 encoding * Decoding the query string from URLs now falls back to the ISO-8859-1 encoding
when the input is not valid UTF-8. 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 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()`` Similarly, the ``use_natural_keys`` argument for ``serializers.serialize()``
has been deprecated. Use ``use_natural_foreign_keys`` instead. has been deprecated. Use ``use_natural_foreign_keys`` instead.

2
docs/releases/1.8.1.txt
View File

@ -75,7 +75,7 @@ Bugfixes
* Fixed a migration crash when renaming the target model of a many-to-many * Fixed a migration crash when renaming the target model of a many-to-many
relation (:ticket:`24725`). 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`). prevented apps with data migrations from using the option (:ticket:`24729`).
* Fixed ``makemessages`` crash in some locales (:ticket:`23271`). * Fixed ``makemessages`` crash in some locales (:ticket:`23271`).

39
docs/releases/1.8.txt
View File

@ -68,9 +68,8 @@ Security enhancements
Several features of the django-secure_ third-party library have been Several features of the django-secure_ third-party library have been
integrated into Django. :class:`django.middleware.security.SecurityMiddleware` integrated into Django. :class:`django.middleware.security.SecurityMiddleware`
provides several security enhancements to the request/response cycle. The new provides several security enhancements to the request/response cycle. The new
:djadminopt:`--deploy` option of the :djadmin:`check` command allows you to :option:`check --deploy` option allows you to check your production settings
check your production settings file for ways to increase the security of your file for ways to increase the security of your site.
site.
.. _django-secure: https://pypi.python.org/pypi/django-secure .. _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. * Commands from alternate package formats like eggs are now also discovered.
* :djadmin:`dumpdata` now has the option :djadminopt:`--output` which allows * The new :option:`dumpdata --output` option allows specifying a file to which
specifying the file to which the serialized data is written. the serialized data is written.
* :djadmin:`makemessages` and :djadmin:`compilemessages` now have the option * The new :option:`makemessages --exclude` and :option:`compilemessages
:djadminopt:`--exclude` which allows exclusion of specific locales from --exclude` options allow excluding specific locales from processing.
processing.
* :djadmin:`compilemessages` now has a ``--use-fuzzy`` or ``-f`` option which * :djadmin:`compilemessages` now has a ``--use-fuzzy`` or ``-f`` option which
includes fuzzy translations into compiled files. includes fuzzy translations into compiled files.
* The :djadminopt:`--ignorenonexistent` option of the :djadmin:`loaddata` * The :option:`loaddata --ignorenonexistent` option now ignores data for models
management command now ignores data for models that no longer exist. that no longer exist.
* :djadmin:`runserver` now uses daemon threads for faster reloading. * :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 * The :djadmin:`dbshell` command now supports MySQL's optional SSL certificate
authority setting (``--ssl-ca``). authority setting (``--ssl-ca``).
* The :djadminopt:`--name` option for :djadmin:`makemigrations` allows you to * The new :option:`makemigrations --name` allows giving the migration(s) a
to give the migration(s) a custom name instead of a generated one. custom name instead of a generated one.
* The :djadmin:`loaddata` command now prevents repeated fixture loading. If * The :djadmin:`loaddata` command now prevents repeated fixture loading. If
:setting:`FIXTURE_DIRS` contains duplicates or a default fixture directory :setting:`FIXTURE_DIRS` contains duplicates or a default fixture directory
path (``app_name/fixtures``), an exception is raised. path (``app_name/fixtures``), an exception is raised.
* :djadmin:`makemigrations` now supports an :djadminopt:`--exit` option to * The new :option:`makemigrations --exit` option allows exiting with an error
exit with an error code if no migrations are created. code if no migrations are created.
* The new :djadmin:`showmigrations` command allows listing all migrations and * The new :djadmin:`showmigrations` command allows listing all migrations and
their dependencies in a project. their dependencies in a project.
@ -637,9 +635,9 @@ Tests
allows you to test that two JSON fragments are not equal. allows you to test that two JSON fragments are not equal.
* Added options to the :djadmin:`test` command to preserve the test database * Added options to the :djadmin:`test` command to preserve the test database
(:djadminopt:`--keepdb`), to run the test cases in reverse order (:option:`--keepdb <test --keepdb>`), to run the test cases in reverse order
(:djadminopt:`--reverse`), and to enable SQL logging for failing tests (:option:`--reverse <test --reverse>`), and to enable SQL logging for failing
(:djadminopt:`--debug-sql`). tests (:option:`--debug-sql <test --debug-sql>`).
* Added the :attr:`~django.test.Response.resolver_match` attribute to test * Added the :attr:`~django.test.Response.resolver_match` attribute to test
client responses. client responses.
@ -1189,10 +1187,9 @@ Miscellaneous
``name`` column won't be dropped from the database. Use ``migrate.py migrate ``name`` column won't be dropped from the database. Use ``migrate.py migrate
--fake-initial`` to fake only the initial migration instead. --fake-initial`` to fake only the initial migration instead.
* :djadmin:`migrate` now accepts the :djadminopt:`--fake-initial` option to * The new :option:`migrate --fake-initial` option allows faking initial
allow faking initial migrations. In 1.7 initial migrations were always migrations. In 1.7, initial migrations were always automatically faked if all
automatically faked if all tables created in an initial migration already tables created in an initial migration already existed.
existed.
* An app *without* migrations with a ``ForeignKey`` to an app *with* migrations * 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 may now result in a foreign key constraint error when migrating the database

11
docs/releases/1.9.txt
View File

@ -131,8 +131,8 @@ degradation.
Running tests in parallel Running tests in parallel
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
The :djadmin:`test` command now supports a :djadminopt:`--parallel` option to The :djadmin:`test` command now supports a :option:`--parallel <test
run a project's tests in multiple processes in parallel. --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 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 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 * Initial migrations are now marked with an :attr:`initial = True
<django.db.migrations.Migration.initial>` class attribute which allows <django.db.migrations.Migration.initial>` class attribute which allows
:djadminopt:`migrate --fake-initial <--fake-initial>` to more easily detect :option:`migrate --fake-initial` to more easily detect initial migrations.
initial migrations.
* Added support for serialization of ``functools.partial`` and ``LazyObject`` * Added support for serialization of ``functools.partial`` and ``LazyObject``
instances. 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. * Support for ``allow_syncdb`` on database routers is removed.
* Automatic syncing of apps without migrations is removed. Migrations are * Automatic syncing of apps without migrations is removed. Migrations are
compulsory for all apps unless you pass the :djadminopt:`--run-syncdb` compulsory for all apps unless you pass the :option:`migrate --run-syncdb`
option to ``migrate``. option.
* The SQL management commands for apps without migrations, ``sql``, ``sqlall``, * The SQL management commands for apps without migrations, ``sql``, ``sqlall``,
``sqlclear``, ``sqldropindexes``, and ``sqlindexes``, are removed. ``sqlclear``, ``sqldropindexes``, and ``sqlindexes``, are removed.

5
docs/topics/auth/default.txt
View File

@ -70,8 +70,9 @@ Create superusers using the :djadmin:`createsuperuser` command::
$ python manage.py createsuperuser --username=joe --email=joe@example.com $ 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 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 created immediately. If you leave off the :option:`--username <createsuperuser
:djadminopt:`--email` options, it will prompt you for those values. --username>` or :option:`--email <createsuperuser --email>` options, it will
prompt you for those values.
Changing passwords Changing passwords
------------------ ------------------

2
docs/topics/cache.txt
View File

@ -216,7 +216,7 @@ Like :djadmin:`migrate`, :djadmin:`createcachetable` won't touch an existing
table. It will only create missing tables. table. It will only create missing tables.
To print the SQL that would be run, rather than run it, use the 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 Multiple databases
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~

3
docs/topics/checks.txt
View File

@ -106,8 +106,7 @@ settings file like this::
def my_check(app_configs, **kwargs): def my_check(app_configs, **kwargs):
... ...
These checks will only be run if the :djadminopt:`--deploy` option is passed to These checks will only be run if the :option:`check --deploy` option is used.
the :djadmin:`check` command.
You can also use ``register`` as a function rather than a decorator by You can also use ``register`` as a function rather than a decorator by
passing a callable object (usually a function) as the first argument passing a callable object (usually a function) as the first argument

9
docs/topics/db/multi-db.txt
View File

@ -76,7 +76,7 @@ Synchronizing your databases
The :djadmin:`migrate` management command operates on one database at a The :djadmin:`migrate` management command operates on one database at a
time. By default, it operates on the ``default`` database, but by 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 <migrate --database>` option, you can tell it
to synchronize a different database. So, to synchronize all models onto to synchronize a different database. So, to synchronize all models onto
all databases in our example, you would need to call:: all databases in our example, you would need to call::
@ -91,10 +91,9 @@ constraining the availability of particular models.
Using other management commands Using other management commands
------------------------------- -------------------------------
The other ``django-admin`` commands that interact with the database The other ``django-admin`` commands that interact with the database operate in
operate in the same way as :djadmin:`migrate` -- they only ever operate the same way as :djadmin:`migrate` -- they only ever operate on one database at
on one database at a time, using :djadminopt:`--database` to control a time, using ``--database`` to control the database used.
the database used.
.. _topics-db-multi-db-routing: .. _topics-db-multi-db-routing:

25
docs/topics/migrations.txt
View File

@ -143,7 +143,7 @@ get both the changes to your models and the accompanying migration at the
same time. same time.
If you want to give the migration(s) a meaningful name instead of a generated 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 $ 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 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). it has no dependencies on any other migration in the same app).
When :djadmin:`migrate` is run with the :djadminopt:`--fake-initial` option, When the :option:`migrate --fake-initial` option is used, these initial
these initial migrations are treated specially. For an initial migration that migrations are treated specially. For an initial migration that creates one or
creates one or more tables (``CreateModel`` operation), Django checks that all more tables (``CreateModel`` operation), Django checks that all of those tables
of those tables already exist in the database and fake-applies the migration already exist in the database and fake-applies the migration if so. Similarly,
if so. Similarly, for an initial migration that adds one or more fields for an initial migration that adds one or more fields (``AddField`` operation),
(``AddField`` operation), Django checks that all of the respective columns Django checks that all of the respective columns already exist in the database
already exist in the database and fake-applies the migration if so. Without and fake-applies the migration if so. Without ``--fake-initial``, initial
:djadminopt:`--fake-initial`, initial migrations are treated no differently migrations are treated no differently from any other migration.
from any other migration.
Adding migrations to apps 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 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 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 initial migration *and* that the tables it wants to create already exist, and
will mark the migration as already applied. (Without the will mark the migration as already applied. (Without the :option:`migrate
:djadminopt:`--fake-initial` flag, the :djadmin:`migrate` command would error --fake-initial` flag, the command would error out because the tables it wants
out because the tables it wants to create already exist.) to create already exist.)
Note that this only works given two things: Note that this only works given two things:

6
docs/topics/serialization.txt
View File

@ -471,8 +471,8 @@ already in use, and do not need to ensure that deserialized objects retain the
same primary keys. same primary keys.
If you are using :djadmin:`dumpdata` to generate serialized data, use the If you are using :djadmin:`dumpdata` to generate serialized data, use the
:djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary` command :option:`dumpdata --natural-foreign` and :option:`dumpdata --natural-primary`
line flags to generate natural keys. command line flags to generate natural keys.
.. note:: .. 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. must exist before you include a natural key reference to that data.
To accommodate this limitation, calls to :djadmin:`dumpdata` that use 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. ``natural_key()`` method before serializing standard primary key objects.
However, this may not always be enough. If your natural key refers to However, this may not always be enough. If your natural key refers to

21
docs/topics/testing/overview.txt
View File

@ -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 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 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 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` ``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 <test --failfast>` option, notice that some tests are unexpectedly failing and
on the failures without waiting for the full test run to complete. 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 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, 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 Regardless of whether the tests pass or fail, the test databases are destroyed
when all the tests have been executed. when all the tests have been executed.
You can prevent the test databases from being destroyed by adding the You can prevent the test databases from being destroyed by using the
:djadminopt:`--keepdb` flag to the test command. This will preserve the test :option:`test --keepdb` option. This will preserve the test database between
database between runs. If the database does not exist, it will first be runs. If the database does not exist, it will first be created. Any migrations
created. Any migrations will also be applied in order to keep it p to date. will also be applied in order to keep it p to date.
The default test database names are created by prepending ``test_`` to the The default test database names are created by prepending ``test_`` to the
value of each :setting:`NAME` in :setting:`DATABASES`. When using SQLite, 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 database by a given :class:`~django.test.TransactionTestCase` test, they
must be updated to be able to run independently. must be updated to be able to run independently.
You may reverse the execution order inside groups by passing You may reverse the execution order inside groups using the :option:`test
:djadminopt:`--reverse` to the test command. This can help with ensuring your --reverse` option. This can help with ensuring your tests are independent from
tests are independent from each other. each other.
.. _test-case-serialized-rollback: .. _test-case-serialized-rollback:

5
docs/topics/testing/tools.txt
View File

@ -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 In earlier versions, the live server's default address was always
``'localhost:8081'``. ``'localhost:8081'``.
If you'd like to select another address then you may pass a different one to If you'd like to select another address, you may pass a different one using the
the :djadmin:`test` command via the :djadminopt:`--liveserver` option, for :option:`test --liveserver` option, for example:
example:
.. code-block:: console .. code-block:: console