Repository navigation
Extended help view, or a man page #4565
Description
I find that the single-page layout of a man page aids with the discoverability of features of a command. While I'm looking for details of the option I need help with, I often see something that I wasn't previously aware of or had forgotten.
This sort of discoverability doesn't exist in the wp help command as it only lists the top level subcommands. Some form of extended help view which lists the description and complete synopsis for every available command could help with discoverability. A trimmed example is below.
It needn't be an actual man page (although a cursory Google shows that it is possible to generate man pages for a non-system command), it could be some form of extended view for help (wp help --extended) but its discoverability would be the main feature.
Thoughts?
$ man wp
NAME
wp
DESCRIPTION
Manage WordPress through the command-line.
SYNOPSIS
wp <command>
SUBCOMMANDS
wp cache add <key> <value> [<group>] [<expiration>]
Add a value to the object cache.
wp cache decr <key> [<offset>] [<group>]
Decrement a value in the object cache.
wp cache delete <key> [<group>]
Remove a value from the object cache.
wp cache flush
Flush the object cache.
wp cache get <key> [<group>]
Get a value from the object cache.
wp cap add <role> <cap>...
Add capabilities to a given role.
wp cap list <role> [--format=<format>]
List capabilities for a given role.
wp cap remove <role> <cap>...
Remove capabilities from a given role.
wp checksum core [--version=<version>] [--locale=<locale>]
Verify WordPress files against WordPress.org's checksums.
wp ...
GLOBAL PARAMETERS
--path=<path>
Path to the WordPress files.
--url=<url>
Pretend request came from given URL. In multisite, this argument is how
the target site is specified.
--ssh=[<scheme>:][<user>@]<host|container>[:<port>][<path>]
Perform operation against a remote server over SSH (or a container using
scheme of "docker", "docker-compose", "vagrant").
--http=<http>
Perform operation against a remote WordPress install over HTTP.
--...
Run 'wp help <command>' to get more information on a specific command.
Activity
danielbachhuber commentedon Dec 12, 2017
I'm amenable to this idea but I think we should take it a bit further. There's a lot of room for improvement in the help docs generally (e.g. wp-cli/ideas#56).
It'd be neat if someone did a review of other CLI tools, documented what was useful about their help docs, and we could crib the best ideas.
danielbachhuber commentedon Dec 12, 2017
Also related wp-cli/ideas#54
danielbachhuber commentedon Dec 14, 2017
Closing in favor of #6244