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, 37 insertions, 39 deletions

diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index e0740a201d..e59f0318cc 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -70,8 +70,9 @@ Create superusers using the :djadmin:`createsuperuser` command::
     $ python manage.py createsuperuser --username=joe --email=joe@example.com
 
 You will be prompted for a password. After you enter one, the user will be
-created immediately. If you leave off the :djadminopt:`--username` or the
-:djadminopt:`--email` options, it will prompt you for those values.
+created immediately. If you leave off the :option:`--username <createsuperuser
+--username>` or :option:`--email <createsuperuser --email>` options, it will
+prompt you for those values.
 
 Changing passwords
 ------------------
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 1a860a71e3..fc0d81abe1 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -216,7 +216,7 @@ Like :djadmin:`migrate`, :djadmin:`createcachetable` won't touch an existing
 table. It will only create missing tables.
 
 To print the SQL that would be run, rather than run it, use the
-:djadminopt:`--dry-run` option.
+:option:`createcachetable --dry-run` option.
 
 Multiple databases
 ~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/checks.txt b/docs/topics/checks.txt
index 5521c9cb8d..b0074891db 100644
--- a/docs/topics/checks.txt
+++ b/docs/topics/checks.txt
@@ -106,8 +106,7 @@ settings file like this::
     def my_check(app_configs, **kwargs):
         ...
 
-These checks will only be run if the :djadminopt:`--deploy` option is passed to
-the :djadmin:`check` command.
+These checks will only be run if the :option:`check --deploy` option is used.
 
 You can also use ``register`` as a function rather than a decorator by
 passing a callable object (usually a function) as the first argument
diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt
index f4b6367033..ca35d1f933 100644
--- a/docs/topics/db/multi-db.txt
+++ b/docs/topics/db/multi-db.txt
@@ -76,7 +76,7 @@ Synchronizing your databases
 
 The :djadmin:`migrate` management command operates on one database at a
 time. By default, it operates on the ``default`` database, but by
-providing a :djadminopt:`--database` argument, you can tell :djadmin:`migrate`
+providing the :option:`--database <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:
 
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index 01b5404fd6..b5e706a9b9 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -143,7 +143,7 @@ get both the changes to your models and the accompanying migration at the
 same time.
 
 If you want to give the migration(s) a meaningful name instead of a generated
-one, you can use the :djadminopt:`--name` option::
+one, you can use the :option:`makemigrations --name` option::
 
     $ python manage.py makemigrations --name changed_my_model your_app_label
 
@@ -291,15 +291,14 @@ migration class. If an ``initial`` class attribute isn't found, a migration
 will be considered "initial" if it is the first migration in the app (i.e. if
 it has no dependencies on any other migration in the same app).
 
-When :djadmin:`migrate` is run with the :djadminopt:`--fake-initial` option,
-these initial migrations are treated specially. For an initial migration that
-creates one or more tables (``CreateModel`` operation), Django checks that all
-of those tables already exist in the database and fake-applies the migration
-if so. Similarly, for an initial migration that adds one or more fields
-(``AddField`` operation), Django checks that all of the respective columns
-already exist in the database and fake-applies the migration if so. Without
-:djadminopt:`--fake-initial`, initial migrations are treated no differently
-from any other migration.
+When the :option:`migrate --fake-initial` option is used, these initial
+migrations are treated specially. For an initial migration that creates one or
+more tables (``CreateModel`` operation), Django checks that all of those tables
+already exist in the database and fake-applies the migration if so. Similarly,
+for an initial migration that adds one or more fields (``AddField`` operation),
+Django checks that all of the respective columns already exist in the database
+and fake-applies the migration if so. Without ``--fake-initial``, initial
+migrations are treated no differently from any other migration.
 
 Adding migrations to apps
 -------------------------
@@ -317,9 +316,9 @@ need to convert it to use migrations; this is a simple process::
 This will make a new initial migration for your app. Now, run ``python
 manage.py migrate --fake-initial``, and Django will detect that you have an
 initial migration *and* that the tables it wants to create already exist, and
-will mark the migration as already applied. (Without the
-:djadminopt:`--fake-initial` flag, the :djadmin:`migrate` command would error
-out because the tables it wants to create already exist.)
+will mark the migration as already applied. (Without the :option:`migrate
+--fake-initial` flag, the command would error out because the tables it wants
+to create already exist.)
 
 Note that this only works given two things:
 
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index 2221463210..ec80efafc0 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -471,8 +471,8 @@ already in use, and do not need to ensure that deserialized objects retain the
 same primary keys.
 
 If you are using :djadmin:`dumpdata` to generate serialized data, use the
-:djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary` command
-line flags to generate natural keys.
+:option:`dumpdata --natural-foreign` and :option:`dumpdata --natural-primary`
+command line flags to generate natural keys.
 
 .. note::
 
@@ -495,7 +495,7 @@ a "forward reference" with natural keys -- the data you're referencing
 must exist before you include a natural key reference to that data.
 
 To accommodate this limitation, calls to :djadmin:`dumpdata` that use
-the :djadminopt:`--natural-foreign` option will serialize any model with a
+the :option:`dumpdata --natural-foreign` option will serialize any model with a
 ``natural_key()`` method before serializing standard primary key objects.
 
 However, this may not always be enough. If your natural key refers to
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt
index 8f01f0c8a8..1674a40a39 100644
--- a/docs/topics/testing/overview.txt
+++ b/docs/topics/testing/overview.txt
@@ -115,9 +115,10 @@ wait for the currently running test to complete and then exit gracefully.
 During a graceful exit the test runner will output details of any test
 failures, report on how many tests were run and how many errors and failures
 were encountered, and destroy any test databases as usual. Thus pressing
-``Ctrl-C`` can be very useful if you forget to pass the :djadminopt:`--failfast`
-option, notice that some tests are unexpectedly failing, and want to get details
-on the failures without waiting for the full test run to complete.
+``Ctrl-C`` can be very useful if you forget to pass the :option:`--failfast
+<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:
 
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index e6e8fe52e9..9c50aa0f9f 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -833,9 +833,8 @@ available port in the ``8081-8179`` range. Its full URL can be accessed with
     In earlier versions, the live server's default address was always
     ``'localhost:8081'``.
 
-If you'd like to select another address then you may pass a different one to
-the :djadmin:`test` command via the :djadminopt:`--liveserver` option, for
-example:
+If you'd like to select another address, you may pass a different one using the
+:option:`test --liveserver` option, for example:
 
 .. code-block:: console