Open porg opened 1 year ago
Thanks for the suggestion, @porg
1) A meta question
Good question, it's definitely not obvious.
All of the help docs are produced by Help_Command
and the functions it calls: https://github.com/wp-cli/wp-cli/blob/d99e2532014d3e0d14999b5f1e4382d9420c8aea/php/commands/src/Help_Command.php
2) The change proposal itself
I'm not sure amending the SYNOPSIS is quite the right place. The SYNOPSIS is meant for the command itself.
I agree that the current location of the text is a bit hidden.
We could potentially inject it at the top of the SUBCOMMANDS section:
Or potentially inject a HELP section to this root doc.
It might be useful to see how other popular CLI tools expose their --help
feature.
--help
for a random choice of CLI apps, which I recently usedgit
is the exception)Those examples are helpful, thank you.
Few more ideas to throw into the mix:
wp
that provides 1-3 paragraphs about WP-CLI with basic usage instructions.wp
that's more specifically focused on getting help (e.g. running wp <help>
, asking for help in #cli
on Slack, etc.)I'd be curious to hear other opinions from @wp-cli/committers
Two thoughts on this:
I'm not against improving on this, just wanted to mention that there are several conflicting goals we're trying to solve for here.
1) A meta question
I wanted to submit a change to the output of purely
wp
itself (aka "help index" aka "manpage index"). Which file(s) are used to build this? The content which starts like:Did a full text search for
Manage WordPress through the command-line
in both https://github.com/wp-cli/handbook and https://github.com/wp-cli/wp-cli but found nothing. I had wanted to submit a change to this as a pull request. But as I was not able to find the source for this, I put my proposal here itself.2) The change proposal itself
In the section "SUBCOMMANDS" the help command itself is summarized like this:
And only at the very end you have:
This is not so ideal. I propose to do one of the following:
a) Amend the SYNOPSIS section.
b) Or in the SUBCOMMANDS section change the help command:
I even would propose to except those from the alphabetical order and put them first, with one empty line inbetween, as they are serve as a quick lookup from more specific help.