Opened 9 years ago

Closed 8 years ago

Last modified 8 years ago

#23868 closed Cleanup/optimization (fixed)

dumpdata options documentation isn't correctly formatted for some options

Reported by: Keryn Knight Owned by: Tim Graham
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: django@… Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (8)

comment:1 by Tim Graham, 9 years ago

Triage Stage: UnreviewedAccepted

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.

comment:2 by andrei kulakov, 9 years ago

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.

comment:3 by Tim Graham, 8 years ago

Owner: changed from nobody to Tim Graham
Status: newassigned

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.

comment:4 by Tim Graham, 8 years ago

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

comment:5 by Tim Graham, 8 years ago

Has patch: set

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+.

comment:6 by Simon Charette, 8 years ago

Triage Stage: AcceptedReady for checkin

comment:7 by Tim Graham <timograham@…>, 8 years ago

Resolution: fixed
Status: assignedclosed

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.

comment:8 by Tim Graham <timograham@…>, 8 years ago

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

Note: See TracTickets for help on using tickets.
Back to Top