New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
cli_parser: man-pages and help text generation using Homebrew::CLI::Parser #4383
Conversation
Can you run |
Library/Homebrew/brew.rb
Outdated
@@ -82,7 +82,7 @@ | |||
# - a help flag is passed AND there is no command specified | |||
# - no arguments are passed | |||
# - if cmd is Cask, let Cask handle the help command instead | |||
if (empty_argv || help_flag) && cmd != "cask" | |||
if (empty_argv || help_flag) && cmd != "cask" && !internal_dev_cmd |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you explain this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Developer Command level OptionParser
would handle respective --help
text generation. Until now Homebrew::Help.help cmd
would be generating the help text.
And we have OptionParser
enabled only for developer commands. Hence the override.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see. I think it would be good to make this part of the Homebrew::Help.help
class instead of here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah. I'll try doing that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also CC @reitermarkus as a note that it'd be good to get Cask's help behaving similar to the rest of Homebrew's.
Library/Homebrew/dev-cmd/audit.rb
Outdated
|
||
If no <formulae> are provided, all of them are checked. | ||
EOS | ||
switch "--strict", description: "Run additional style checks, including Rubocop style checks." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you think about making the second argument default to a description here? The description:
feel maybe a bit redundant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
switch
's first two arguments are already being specified for short and long options . eg:
switch "-s", "--strict"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
May be we can separate them out by checking if they start with -
and doesn't contain any
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe short options could be short: "-s"
or something instead? They'll be used less than descriptions, right?
Library/Homebrew/dev-cmd/audit.rb
Outdated
switch "--strict", description: "Run additional style checks, including Rubocop style checks." | ||
switch "--online", description: "Run additional slower style checks that require a\nnetwork connection." | ||
switch "--new-formula", description: "Run various additional style checks to determine if a new formula \nis eligible for Homebrew. This should be used when creating \nnew formula and implies --strict and --online." | ||
switch "--fix", description: "Fix style violations automatically using\nRuboCop's auto-correct feature." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
<<~EOS
is preferable to \n
here.
I've been caught up at work.. will get back working on this in 3 days. |
@MikeMcQuaid From what I see, Man pages are formatted differently, we cannot directly use the help text as-is, but it CAN be used by writing some extra code. I looked at the man pages of Before proceeding, I have a question to clarify on help text rephrasing.
(snipped)
Since
to
Do we want to keep the current help text as-is , or rephrase it to latter ? |
Cool, looks good thanks @GauthamGoli.
This would be great 👍 |
I was facing formatting issues and had given up temporarily. I will give it a try again now to get the formatting right. |
@GauthamGoli Thanks! We could always write our own generator if that'd be better. |
@MikeMcQuaid Can you please generate manpage and let me know what you think? (Wrote a simple generator, I think its better now) |
31e584c
to
da429c0
Compare
@GauthamGoli Yeh, looks nicer. Could still be tweaked further I think but that's a big step up on what there was before 👍 |
@MikeMcQuaid Let me know at what places? I'll do it and lets ship this finally, its been too long this PR has been open 😅 😅 |
Library/Homebrew/utils/formatter.rb
Outdated
@@ -31,6 +31,10 @@ def error(string, label: nil) | |||
label(label, string, :red) | |||
end | |||
|
|||
def wrap(s, width = 172, indentation = 0) | |||
" "*indentation + s.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n").gsub("\n", "\n"+" "*indentation) + "\n" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is hard to follow. Could you use intermediate variables and/or string interpolation and put each .gsub
on a new line?
Library/Homebrew/cli_parser.rb
Outdated
end | ||
|
||
def wrap_option_desc(desc) | ||
Formatter.wrap(desc, @desc_line_length).split("\n") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What happens without these being wrapped? Is it the manpage/markdown/something else that looks weird?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If not wrapped this way, In the help text , option description would be in a single line and wrapped based on terminal's width and new line starts without any indentation which would look weird like below
--online Run additional slower style checks that require a
network connection.
When lines are wrapped and passed as an array, OptionParser
's help text generator would show it with proper indentation.
--online Run additional slower style checks that require a
network connection.
Manpage formatting is handled separately in man.rb
itself.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@GauthamGoli I see, thanks 👍
Library/Homebrew/cli_parser.rb
Outdated
@@ -34,9 +48,18 @@ def switch(*names, description: nil, env: nil, required_for: nil, depends_on: ni | |||
enable_switch(*names) if !env.nil? && !ENV["HOMEBREW_#{env.to_s.upcase}"].nil? | |||
end | |||
|
|||
def banner(text) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is the banner the help text? If so, a name relating to that might be more obvious.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Banner is a brief description of the command shown above the options.
Ex:
banner <<~EOS
Usage: brew audit [options] [<formulae>]
Check <formulae> for Homebrew coding style violations. This should be
run before submitting a new formula.
If no <formulae> are provided, all of them are checked.
EOS
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@GauthamGoli Ok, I see. Maybe usage_banner
or help_banner
or similar?
Library/Homebrew/cli_parser.rb
Outdated
when :verbose then [["-v", "--verbose"], :verbose] | ||
when :debug then [["-d", "--debug"], :debug] | ||
when :force then [["-f", "--force"], :force] | ||
when :quiet then [["-q", "--quiet"], :quiet, "Suppress warnings."] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suppress any warnings
Library/Homebrew/cli_parser.rb
Outdated
when :force then [["-f", "--force"], :force] | ||
when :quiet then [["-q", "--quiet"], :quiet, "Suppress warnings."] | ||
when :verbose then [["-v", "--verbose"], :verbose, "Verbose mode."] | ||
when :debug then [["-d", "--debug"], :debug, "Display debug info."] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Display any debugging information
Library/Homebrew/cli_parser.rb
Outdated
when :debug then [["-d", "--debug"], :debug] | ||
when :force then [["-f", "--force"], :force] | ||
when :quiet then [["-q", "--quiet"], :quiet, "Suppress warnings."] | ||
when :verbose then [["-v", "--verbose"], :verbose, "Verbose mode."] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Make some output more verbose
Library/Homebrew/cli_parser.rb
Outdated
when :quiet then [["-q", "--quiet"], :quiet, "Suppress warnings."] | ||
when :verbose then [["-v", "--verbose"], :verbose, "Verbose mode."] | ||
when :debug then [["-d", "--debug"], :debug, "Display debug info."] | ||
when :force then [["-f", "--force"], :force, "Override any warnings/validations."] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Override warnings and enable potentially unsafe operations
Library/Homebrew/dev-cmd/audit.rb
Outdated
EOS | ||
switch "--strict", description: "Run additional style checks, including Rubocop style checks." | ||
switch "--online", description: "Run additional slower style checks that require a network connection." | ||
switch "--new-formula", description: "Run various additional style checks to determine if a new formula is eligible for Homebrew. This should be used when creating new formula and implies --strict and --online." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This line (and some others) is a bit too long. Maybe stick each description:
on a new line?
@GauthamGoli Good work on this! I think ideally if we're writing our own output I'd just aim for the output to be as close as possible to the existing rendered manpage output i.e. do stuff like |
@MikeMcQuaid The current manpage output for Do you think its worth transitioning to this new format ? If not, I'll make it as close to existing format. |
Yes, let's just do it 👍. Looking at the
|
6f00f8c
to
5f71418
Compare
@MikeMcQuaid addressed the comments. Please take a look when you get time! If this code style is OK, I'll do the same for other developer commands. Do we plan to remove the comments in the beginning of every |
Library/Homebrew/dev-cmd/audit.rb
Outdated
|
||
EOS | ||
switch "--strict", description: "Run additional style checks, "\ | ||
"including Rubocop style checks." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What about:
switch "--strict",
description: "Run additional style checks, including Rubocop style checks."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In the current style, one could see all the declared options in a single column (I think its more readable this way but with trade off of having description spanning multiple lines), but with above style the description would come in between. I would defer the final call on this to you @MikeMcQuaid
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it'd be preferable to be able to have the description on a single line, thanks 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@MikeMcQuaid I've updated, can you see if this is okay?
Provided e.g.
The manpage style is perfect. I agree it's actually better than the current style now 😍. There will be some slight inconsistency when the previous command style is used just for non-developer commands but I think it's worth it to get this merged. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
brew audit --help
seems to be still running the audit command. Additionally, it'd be nice if the options were bolded there. Other than that 👍 👏 🎉
Library/Homebrew/dev-cmd/audit.rb
Outdated
run before submitting a new formula. | ||
|
||
If no <formulae> are provided, all of them are checked. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Might be nice to make it so you don't need this trailing empty line?
Library/Homebrew/dev-cmd/audit.rb
Outdated
If no <formulae> are provided, all of them are checked. | ||
|
||
EOS | ||
switch "--strict", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, terrible pedantry now but given the way description
is I'd be tempted to say that switch "--strict",
would look better.
077c111
to
a02c3b9
Compare
@MikeMcQuaid Now manpages for all dev commands are being generated through this. Can you once take a look, and let me know your thoughts? Thanks. There are minor hiccups like |
@GauthamGoli I think it would be good if there was a bit more visual separation between commands either through indentation, keeping options on the same line as their first line of description or something else.
Agreed, would be good to resolve this before merge. There could be a "global options" or similar section that apply to all commands. |
@MikeMcQuaid Is the indentation fine now? I made the command synopsis to be H3 ( ###) |
Looks great 😍.
After that: I think we're good to go. So close now! Great work again @GauthamGoli! |
@MikeMcQuaid Now |
@MikeMcQuaid any idea why the build is failing? |
@GauthamGoli Fixing in Homebrew/homebrew-test-bot#201 then will rerun. |
Great work again @GauthamGoli 🎉 |
brew style
with your changes locally?brew tests
with your changes locally?#4271 (comment)
This PR is about generating
--help
text usingOptionParser
and to get feedback on the interface, and the way help text is being shown as its different from what we currently show.brew audit --help
would return something like this.