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.

4 files changed, 28 insertions, 32 deletions

diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt
index 0d75739e48..343ede1949 100644
--- a/docs/ref/contrib/contenttypes.txt
+++ b/docs/ref/contrib/contenttypes.txt
@@ -320,8 +320,7 @@ model:
    generic relations, you should probably be using a natural key to uniquely
    identify related :class:`~django.contrib.contenttypes.models.ContentType`
    objects. See :ref:`natural keys<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`;
diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt
index d22621aafe..71f3863f4b 100644
--- a/docs/ref/contrib/gis/commands.txt
+++ b/docs/ref/contrib/gis/commands.txt
@@ -12,35 +12,35 @@ When :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`, the
 The overridden command is spatially-aware, and places geometry fields in the
 auto-generated model definition, where appropriate.
 
-ogrinspect <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.
diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt
index 822b338e2e..58c5e71a31 100644
--- a/docs/ref/contrib/sitemaps.txt
+++ b/docs/ref/contrib/sitemaps.txt
@@ -519,7 +519,7 @@ each time you call ``save()``.
 Pinging Google via ``manage.py``
 --------------------------------
 
-.. django-admin:: ping_google
+.. django-admin:: ping_google [sitemap_url]
 
 Once the sitemaps application is added to your project, you may also
 ping Google using the ``ping_google`` management command::
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index e6caa53e32..b6da4b98d2 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -49,8 +49,8 @@ can help show you which files are found.
 On subsequent ``collectstatic`` runs (if ``STATIC_ROOT`` isn't empty), files
 are copied only if they have a modified timestamp greater than the timestamp of
 the file in ``STATIC_ROOT``. Therefore if you remove an application from
-:setting:`INSTALLED_APPS`, it's a good idea to use the :djadminopt:`--clear`
-option in order to remove stale static files.
+:setting:`INSTALLED_APPS`, it's a good idea to use the :option:`collectstatic
+--clear` option in order to remove stale static files.
 
 Files are searched by using the :setting:`enabled finders
 <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