--help needs some love

Bug #1582506 reported by Gustavo Niemeyer
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Fix Released
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.

Tags: snap-docs
Revision history for this message
Sergio Schvezov (sergiusens) wrote :

This change means we would need to move away from docopts

Changed in snapcraft:
status: New → Triaged
importance: Undecided → Medium
Revision history for this message
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)
Revision history for this message
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  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.