dumpdata options documentation isn't correctly formatted for some options

[Keryn Knight]

Specifically, ​dumpdata <app_label app_label ...> gives --format, --pks, --indent etc their own headings, but --exclude and --database are formatted in such a way that they look like addendums to the --indent documentation.

Also, --pks lacks a demonstrative example that --format and --indent provide (eg: <pk,pk,pk ...> or whatever). I'd suggest that example argument formats should also be given to --exclude and --database, if hoisted to headings.

An argument could be made that because both are common options (documented under common options) they needn't even be covered here, I suppose, though given dumpdata exports unmanaged models (which it may not be able to) I'd say the --exclude is pertinent. If hoisting to their own headings is undesirable because they're already headings elsewhere, the paragraphs should probably be moved to the preamble which includes explaining --all as prose.

[Tim Graham]

As you alluded to, the problem is that because they are common options, we can't include them multiple times using .. django-admin-option::`. We can improve things however you like though.

[andrei kulakov]

I think it would make sense if common options would be always given either before the specific options or after; it's better to have them before specific options because otherwise they do look like they're part of the option that precedes them.

Alternatively there may be a short paragraph before the first option that simply lists the common option names and links to common options section. The downside of this approach is that common options like --database and --exclude are very important and perhaps deserve at least a short description in each section. On the third hand, they are more or less self-descriptive so perhaps they don't. A reader probably won't miss them anyway since the name of the option is bolded.

[Tim Graham]

I think we need to modify the parse_django_adminopt_node() function in docs/_ext/djangodocs.py to allow declaring the options like this .. django-admin-option:: runserver --nothreading (with the command name). That removes the restriction that commands cannot share options. Unfortunately, this will require updating all the documentation references to options as well.

I'll try to do this as it's blocking #25735 which adds a --tag option to the test command which is already implemented by check.

[Tim Graham]

This is coming along and I hope to finish tomorrow: ​WIP PR

[Tim Graham]

Should be ready for review now. The other task that must be completed before merging this is figuring out why the docs builds crashes on djangoproject.com with Sphinx 1.3+.

[Tim Graham <timograham@…>]

In e519aab4:

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.

[Tim Graham <timograham@…>]

In d7a60868:

[1.9.x] 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.

Backport of e519aab43a419589e92fe284e4ce2f2e034aec6a from master