--help needs some love

Bug #1582506 reported by Gustavo Niemeyer on 2016-05-17
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Snapcraft
High
Sergio Schvezov

Bug Description

Typing "snapcraft <any subcommand> --help" shows the same output of "snapcraft --help".

For clarity, each subcommand should hold its own documentation, and options for subcommands should be removed from the global documentation.

There's also no need to have a huge usage list at the top. Usage for each subcommand should ideally be inside that specific subcommand's help.

Also, the summary of the "build" stage holds documentation for its option:

"""
  clean Remove content - cleans downloads, builds or install artifacts.
  pull Download or retrieve artifacts defined for a part.
  build Build artifacts defined for a part. Build systems capable of
               running parallel build jobs will do so unless
               "--no-parallel-build" is specified.
"""

The option should be documented under the options header as usual, instead of the summary.

Also, these summaries might be moved to the third person perhaps. E.g.:

  pull Downloads or retrieves artifacts defined for a part.

and the "clean" one might also be shortened to something like:

  clean Removes downloads, builds, or install artifacts.

Anyway, sorry for the sausage report. This is all related, but not quite.

Sergio Schvezov (sergiusens) wrote :

This change means we would need to move away from docopts

Changed in snapcraft:
status: New → Triaged
importance: Undecided → Medium
Leo Arias (elopio) wrote :

Raising the priority, because the help is pretty bad now with the big list of snapcraft commands that we have.

tags: added: snap-docs
Changed in snapcraft:
importance: Medium → High
Changed in snapcraft:
milestone: none → 2.30
assignee: nobody → Sergio Schvezov (sergiusens)
no longer affects: snapcraft (Ubuntu)
Sergio Schvezov (sergiusens) wrote :
Changed in snapcraft:
status: Triaged → Fix Committed
Changed in snapcraft:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers