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.

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):
         """

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):

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.

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</ref/django-admin>` can accept some
-default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
+:doc:`management commands</ref/django-admin>` 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
 -------

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
 =================

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)::
 

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.
 

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

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<topics-serialization-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`;

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 <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
 :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 <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``
    keyword option to the field definition.  Set with ``true`` to apply
    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
    :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 <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 <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 <ogrinspect-intro>`.
    in the generated model rather than
    :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
    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.
 
-.. 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``
    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.

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::

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
 <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:
 
-.. 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 <pattern>
-.. django-admin-option:: --ignore <pattern>
+.. 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<INSTALLED_APPS>` and adds automatic serving of static

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
 

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.

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

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

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

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 %}<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.

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.

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`).

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 <test --keepdb>`), to run the test cases in reverse order
+  (:option:`--reverse <test --reverse>`), and to enable SQL logging for failing
+  tests (:option:`--debug-sql <test --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

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 <test
+--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
   <django.db.migrations.Migration.initial>` 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.

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 <createsuperuser
+--username>` or :option:`--email <createsuperuser --email>` options, it will
+prompt you for those values.
 
 Changing passwords
 ------------------

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
 ~~~~~~~~~~~~~~~~~~

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

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 <migrate --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:
 

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:
 

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

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
+<test --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:
 

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