Opened 8 years ago

Closed 7 years ago

Last modified 7 years ago

#24134 closed Cleanup/optimization (fixed)

Document short command line options for management commands

Reported by: Marc Tamlyn Owned by: Tim Graham
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

We are very inconsistent with providing short options for command line flags for management commands. For example, the options provided by the test runner to ./manage.py test all have short options, but the options provided by the management command itself all do not. (-t means --top-level-directory, but there is also --testrunner which has no alternative).

I'm not sure what the correct course of action is but there should be some consistency. Short options are patchily documented - some are, some are not.

Change History (11)

comment:1 Changed 8 years ago by Claude Paroz

OK to consistently document all options, short or long, but I don't see the need to deprecate short options.

comment:2 Changed 8 years ago by Russell Keith-Magee

Agreed that we should be documenting them consistently, and options should be consistently used between commands, but I don't think it follows that every option needs to have a short version, nor that we need to deprecate short options entirely.

-v is a good example - it's convenient to be able to use -v instead of --verbose; it's a commonly used option. But everywhere that --verbose is available, -v is (or should be) the short option. But if a command also had a --very-important-flag-we-use-rarely, the fact that there is a collision on -v doesn't mean we should stop using it for the common option, --verbose.

comment:3 Changed 7 years ago by Tim Graham

Component: Core (Management commands)Documentation
Summary: Deprecate short command line options for management commands?Document short command line options for management commands
Triage Stage: UnreviewedAccepted

comment:4 Changed 7 years ago by Stephan Klinger

Owner: changed from nobody to Stephan Klinger
Status: newassigned

comment:5 Changed 7 years ago by Stephan Klinger

I work on updating the documentation with the available but not yet documented short versions.

comment:6 Changed 7 years ago by Stephan Klinger

Triage Stage: AcceptedReady for checkin

comment:7 Changed 7 years ago by Tim Graham

Has patch: set
Patch needs improvement: set
Triage Stage: Ready for checkinAccepted

The docs build doesn't pass with this change.

comment:8 Changed 7 years ago by Tim Graham

Owner: changed from Stephan Klinger to Tim Graham

I'm working on this as part of #23868.

comment:9 Changed 7 years ago by Tim Graham

Patch needs improvement: unset

PR is ready for review.

comment:10 Changed 7 years ago by Tim Graham <timograham@…>

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:11 Changed 7 years ago by 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

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