Improving usefulness of management command help output via reordering options

[David Foster]

Currently if you run a custom management command with --help, you will get output that looks like:

$ python3 manage.py import_layout_calendar --help

usage: manage.py import_layout_calendar [-h] [--version] [-v {0,1,2,3}]

                                        [--settings SETTINGS]

                                        [--pythonpath PYTHONPATH]

                                        [--traceback] [--no-color]

                                        [--simulate] [--no-strict] [--debug]

                                        [--replace] [--fast-validate]

                                        [args [args ...]]

Imports the calendar for a layout in the database.

positional arguments:

  args

optional arguments:

  -h, --help            show this help message and exit

  --version             show program's version number and exit

  -v {0,1,2,3}, --verbosity {0,1,2,3}

                        Verbosity level; 0=minimal output, 1=normal output,

                        2=verbose output, 3=very verbose output

  --settings SETTINGS   The Python path to a settings module, e.g.

                        "myproject.settings.main". If this isn't provided, the

                        DJANGO_SETTINGS_MODULE environment variable will be

                        used.

  --pythonpath PYTHONPATH

                        A directory to add to the Python path, e.g.

                        "/home/djangoprojects/myproject".

  --traceback           Raise on CommandError exceptions

  --no-color            Don't colorize the command output.

  --simulate            Suppress all database modifications

  --no-strict, -S       Do not promote all warnings to errors

  --debug               Perform all validating and importing live, without

                        capturing output

  --replace             Delete the current layout overlay before importing.

  --fast-validate       Disables full simulated import as part of validation

I have highlighted in yellow the useful information specific to the command that is *not* boilerplate. Notice that most of this yellow text is at the end of the output, with the boilerplate dominating what the user reads first.

I propose reordering the options in the output so that the useful information is at the *beginning* rather than the end, so that it looks more like the following:

$ python3 manage.py import_layout_calendar --help

usage: manage.py import_layout_calendar [-h] [--simulate] [--no-strict]

                                        [--debug] [--replace]

                                        [--fast-validate] [--version]

                                        [-v {0,1,2,3}] [--settings SETTINGS]

                                        [--pythonpath PYTHONPATH]

                                        [--traceback] [--no-color]

                                        [args [args ...]]

Imports the calendar for a layout in the database.

positional arguments:

  args                  <layout_id> | <layout_filepath> <layout_day_duration>

optional arguments:

  -h, --help            show this help message and exit

  --simulate            Suppress all database modifications

  --no-strict, -S       Do not promote all warnings to errors

  --debug               Perform all validating and importing live, without

                        capturing output

  --replace             Delete the current layout overlay before importing.

  --fast-validate       Disables full simulated import as part of validation

  --version             show program's version number and exit

  -v {0,1,2,3}, --verbosity {0,1,2,3}

                        Verbosity level; 0=minimal output, 1=normal output,

                        2=verbose output, 3=very verbose output

  --settings SETTINGS   The Python path to a settings module, e.g.

                        "myproject.settings.main". If this isn't provided, the

                        DJANGO_SETTINGS_MODULE environment variable will be

                        used.

  --pythonpath PYTHONPATH

                        A directory to add to the Python path, e.g.

                        "/home/djangoprojects/myproject".

  --traceback           Raise on CommandError exceptions

  --no-color            Don't colorize the command output.

Thoughts?

--

David Foster | Seattle, WA, USA

[Carlton Gibson]

Hi David. 

Your suggestion seems sensible, good even. (To me at least. 🙂) 

If you'd be happy to do the work for it then a Trac ticket + PR would be the way to go. 

(Assuming there are no objections.) 

Kind Regards,

Carlton

[Adam Johnson]

+1 Seems sensible to me too! Maybe the common arguments can even be put under a header like 'common arguments', if argparse allows that.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscribe@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/658e0ea7-f226-4de0-b90c-3631d0e4a4ef%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Adam