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.

8 files changed, 51 insertions, 61 deletions

diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index ff6900243f..57478ee285 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -219,22 +219,20 @@ Internationalization
 Management Commands
 ^^^^^^^^^^^^^^^^^^^
 
-* The new :djadminopt:`--fail-level` option of the :djadmin:`check` command
-  allows specifying the message level that will cause the command to exit with
-  a non-zero status.
+* The new :option:`check --fail-level` option allows specifying the message
+  level that will cause the command to exit with a non-zero status.
 
-* The new :djadminopt:`makemigrations --check <--check>` option makes the
-  command exit with a non-zero status when model changes without migrations are
-  detected.
+* The new :option:`makemigrations --check` option makes the command exit
+  with a non-zero status when model changes without migrations are detected.
 
 * :djadmin:`makemigrations` now displays the path to the migration files that
   it generates.
 
-* The :djadmin:`shell` ``--interface`` option now accepts ``python`` to force
-  use of the "plain" Python interpreter.
+* The :option:`shell --interface` option now accepts ``python`` to force use of
+  the "plain" Python interpreter.
 
-* The new :djadminopt:`shell --command <--command>` option lets you run a
-  command as Django and exit, instead of opening the interactive shell.
+* The new :option:`shell --command` option lets you run a command as Django and
+  exit, instead of opening the interactive shell.
 
 Migrations
 ^^^^^^^^^^
@@ -510,7 +508,7 @@ Miscellaneous
 ~~~~~~~~~~~~~
 
 * The ``makemigrations --exit`` option is deprecated in favor of the
-  :djadminopt:`--check` option.
+  :option:`makemigrations --check` option.
 
 * ``django.utils.functional.allow_lazy()`` is deprecated in favor of the new
   :func:`~django.utils.functional.keep_lazy` function which can be used with a
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index fa08b717bd..0aedf23ede 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -622,8 +622,7 @@ Django 1.4 also includes several smaller improvements worth noting:
   This should make it easier to read when debugging interaction with
   client-side JavaScript.
 
-* Added the :djadminopt:`--no-location` option to the :djadmin:`makemessages`
-  command.
+* Added the :option:`makemessages --no-location` option.
 
 * Changed the ``locmem`` cache backend to use
   ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other
@@ -1139,7 +1138,7 @@ Development Server Multithreading
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The development server is now is multithreaded by default. Use the
-:djadminopt:`--nothreading` option to disable the use of threading in the
+:option:`runserver --nothreading` option to disable the use of threading in the
 development server::
 
     django-admin.py runserver --nothreading
diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt
index 97e248423c..44f96d248c 100644
--- a/docs/releases/1.5.txt
+++ b/docs/releases/1.5.txt
@@ -315,9 +315,8 @@ Django 1.5 also includes several smaller improvements worth noting:
   whenever a user fails to login successfully. See
   :data:`~django.contrib.auth.signals.user_login_failed`
 
-* The loaddata management command now supports an
-  :djadminopt:`--ignorenonexistent` option to ignore data for fields that no
-  longer exist.
+* The new :option:`loaddata --ignorenonexistent` option ignore data for fields
+  that no longer exist.
 
 * :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
   :meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow
@@ -635,7 +634,7 @@ Behavior of ``syncdb`` with multiple databases
 types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions
 (when :mod:`~django.contrib.auth` is enabled) should be created in the target
 database. Previously, it created them in the default database, even when
-another database was specified with the :djadminopt:`--database` option.
+another database was specified with the ``--database`` option.
 
 If you use ``syncdb`` on multiple databases, you should ensure that
 your routers allow synchronizing content types and permissions to only one of
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt
index 6e03178620..bb24f60969 100644
--- a/docs/releases/1.6.txt
+++ b/docs/releases/1.6.txt
@@ -287,9 +287,8 @@ Minor features
   and :func:`~django.contrib.auth.views.password_change`, you can now pass
   URL names and they will be resolved.
 
-* The :djadmin:`dumpdata` ``manage.py`` command now has a :djadminopt:`--pks`
-  option which will allow users to specify the primary keys of objects they
-  want to dump. This option can only be used with one model.
+* The new :option:`dumpdata --pks` option specifies the primary keys of objects
+  to dump. This option can only be used with one model.
 
 * Added ``QuerySet`` methods :meth:`~django.db.models.query.QuerySet.first`
   and :meth:`~django.db.models.query.QuerySet.last` which are convenience
@@ -905,7 +904,7 @@ Miscellaneous
 
 * If a ``NoReverseMatch`` exception is raised from a method when rendering a
   template, it is not silenced. For example, ``{{ obj.view_href }}`` will
-  cause template rendering to fail if ``view_href()`` raises 
+  cause template rendering to fail if ``view_href()`` raises
   ``NoReverseMatch``. There is no change to the :ttag:`{% url %}<url>` tag, it
   causes template rendering to fail like always when ``NoReverseMatch`` is
   raised.
@@ -946,9 +945,8 @@ Miscellaneous
 * :meth:`~django.core.validators.validate_email` now accepts email addresses
   with ``localhost`` as the domain.
 
-* The :djadminopt:`--keep-pot` option was added to :djadmin:`makemessages`
-  to prevent django from deleting the temporary .pot file it generates before
-  creating the .po file.
+* The new :option:`makemessages --keep-pot` option prevents deleting the
+  temporary .pot file generated before creating the .po file.
 
 * The undocumented ``django.core.servers.basehttp.WSGIServerException`` has
   been removed. Use ``socket.error`` provided by the standard library instead.
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index fc09f5f99d..005882afe6 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -698,16 +698,16 @@ Internationalization
 Management Commands
 ^^^^^^^^^^^^^^^^^^^
 
-* The :djadminopt:`--no-color` option for ``django-admin`` allows you to
-  disable the colorization of management command output.
+* The new :option:`--no-color` option for ``django-admin`` disables the
+  colorization of management command output.
 
-* The new :djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary`
-  options for :djadmin:`dumpdata`, and the new ``use_natural_foreign_keys`` and
+* The new :option:`dumpdata --natural-foreign` and :option:`dumpdata
+  --natural-primary` options, and the new ``use_natural_foreign_keys`` and
   ``use_natural_primary_keys`` arguments for ``serializers.serialize()``, allow
   the use of natural primary keys when serializing.
 
 * It is no longer necessary to provide the cache table name or the
-  :djadminopt:`--database` option for the :djadmin:`createcachetable` command.
+  ``--database`` option for the :djadmin:`createcachetable` command.
   Django takes this information from your settings file. If you have configured
   multiple caches or multiple databases, all cache tables are created.
 
@@ -1444,8 +1444,8 @@ Miscellaneous
 
 * The ``sql*`` management commands now respect the ``allow_migrate()`` method
   of :setting:`DATABASE_ROUTERS`. If you have models synced to non-default
-  databases, use the :djadminopt:`--database` flag to get SQL for those
-  models (previously they would always be included in the output).
+  databases, use the ``--database`` flag to get SQL for those models
+  (previously they would always be included in the output).
 
 * Decoding the query string from URLs now falls back to the ISO-8859-1 encoding
   when the input is not valid UTF-8.
@@ -1624,7 +1624,7 @@ Natural key serialization options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` have been
-deprecated. Use :djadminopt:`--natural-foreign` instead.
+deprecated. Use :option:`dumpdata --natural-foreign` instead.
 
 Similarly, the ``use_natural_keys`` argument for ``serializers.serialize()``
 has been deprecated. Use ``use_natural_foreign_keys`` instead.
diff --git a/docs/releases/1.8.1.txt b/docs/releases/1.8.1.txt
index b01b09e081..09b602c5c4 100644
--- a/docs/releases/1.8.1.txt
+++ b/docs/releases/1.8.1.txt
@@ -75,7 +75,7 @@ Bugfixes
 * Fixed a migration crash when renaming the target model of a many-to-many
   relation (:ticket:`24725`).
 
-* Removed flushing of the test database with :djadminopt:`--keepdb`, which
+* Removed flushing of the test database with :option:`test --keepdb`, which
   prevented apps with data migrations from using the option (:ticket:`24729`).
 
 * Fixed ``makemessages`` crash in some locales (:ticket:`23271`).
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index 7f165ad1a9..d75250082e 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -68,9 +68,8 @@ Security enhancements
 Several features of the django-secure_ third-party library have been
 integrated into Django. :class:`django.middleware.security.SecurityMiddleware`
 provides several security enhancements to the request/response cycle. The new
-:djadminopt:`--deploy` option of the :djadmin:`check` command allows you to
-check your production settings file for ways to increase the security of your
-site.
+:option:`check --deploy` option allows you to check your production settings
+file for ways to increase the security of your site.
 
 .. _django-secure: https://pypi.python.org/pypi/django-secure
 
@@ -410,18 +409,17 @@ Management Commands
 
 * Commands from alternate package formats like eggs are now also discovered.
 
-* :djadmin:`dumpdata` now has the option :djadminopt:`--output` which allows
-  specifying the file to which the serialized data is written.
+* The new :option:`dumpdata --output` option allows specifying a file to which
+  the serialized data is written.
 
-* :djadmin:`makemessages` and :djadmin:`compilemessages` now have the option
-  :djadminopt:`--exclude` which allows exclusion of specific locales from
-  processing.
+* The new :option:`makemessages --exclude` and :option:`compilemessages
+  --exclude` options allow excluding specific locales from processing.
 
 * :djadmin:`compilemessages` now has a ``--use-fuzzy`` or ``-f`` option which
   includes fuzzy translations into compiled files.
 
-* The :djadminopt:`--ignorenonexistent` option of the :djadmin:`loaddata`
-  management command now ignores data for models that no longer exist.
+* The :option:`loaddata --ignorenonexistent` option now ignores data for models
+  that no longer exist.
 
 * :djadmin:`runserver` now uses daemon threads for faster reloading.
 
@@ -439,15 +437,15 @@ Management Commands
 * The :djadmin:`dbshell` command now supports MySQL's optional SSL certificate
   authority setting (``--ssl-ca``).
 
-* The :djadminopt:`--name` option for :djadmin:`makemigrations` allows you to
-  to give the migration(s) a custom name instead of a generated one.
+* The new :option:`makemigrations --name` allows giving the migration(s) a
+  custom name instead of a generated one.
 
 * The :djadmin:`loaddata` command now prevents repeated fixture loading. If
   :setting:`FIXTURE_DIRS` contains duplicates or a default fixture directory
   path (``app_name/fixtures``), an exception is raised.
 
-* :djadmin:`makemigrations` now supports an :djadminopt:`--exit` option to
-  exit with an error code if no migrations are created.
+* The new :option:`makemigrations --exit` option allows exiting with an error
+  code if no migrations are created.
 
 * The new :djadmin:`showmigrations` command allows listing all migrations and
   their dependencies in a project.
@@ -637,9 +635,9 @@ Tests
   allows you to test that two JSON fragments are not equal.
 
 * Added options to the :djadmin:`test` command to preserve the test database
-  (:djadminopt:`--keepdb`), to run the test cases in reverse order
-  (:djadminopt:`--reverse`), and to enable SQL logging for failing tests
-  (:djadminopt:`--debug-sql`).
+  (:option:`--keepdb <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
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 35c673b4f1..a74798b928 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -131,8 +131,8 @@ degradation.
 Running tests in parallel
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :djadmin:`test` command now supports a :djadminopt:`--parallel` option to
-run a project's tests in multiple processes in parallel.
+The :djadmin:`test` command now supports a :option:`--parallel <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.