`brew docs` as an alias for `open https://docs.brew.sh`

[jmfayard]

Provide a detailed description of the proposed feature

brew docs as a shortcut for open https://docs.brew.sh

Also udpate brew help

$ brew help
(....)
Further help:
  brew commands
  brew help [COMMAND]
  man brew
-  https://docs.brew.sh
+ brew docs

What is the motivation for the feature?

Laziness is one of the three great virtues of the programmer, as defined by Larry Wall.

Laziness is the quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don't have to answer so many questions about it.

How will the feature be relevant to at least 90% of Homebrew users?

Benefits for users

It makes it marginally easier to 90% of Homebrew users to access the docs at https://docs.brew.sh

And maybe find the information they need, which is nice.

Benefits for maintainers

It is marginally nicer for Homebrew maintainers that Homebrew users are empowered to find the documentation they need. They would have to repeat themselves marginally less.

Of course, many users still won't read the docs, but now maintainers can reply

This is documented in $ brew docs, section Common Issues

This kind of reply makes it marginally more likely that users read the docs next time.
Yes it's just a RTFM, but I think/hope it's an empowering "Read the Friendly Manual" RTFM, not the "Read the Fucking Manual" RTFM.

Benefits for documentation writers

As someone who writes technical documentation myself, I know this is hard work and I know that I like it when more users actually use and benefit from the documentation.

What alternatives to the feature have been considered?

Bookmarking https://docs.brew.sh

But I'm too lazy to bookmark things and use browser bookmarks correctly.

[carlocab]

I'm open to a brew docs command, but I'd probably still keep https://docs.brew.sh in brew help for the benefit of users who are too lazy to type another command, and want to click on a URL instead.

[MikeMcQuaid]

I love, admire and agree with the honest admission of laziness here. Given how little code would be required to implement this: would definitely review a PR.

[RandomDSdevel]

     These may well not be blocking comments regarding an initial implementation, as these could also be potential future extensions to an initial minimum viable product, but I have a few additional thoughts on some things to keep in mind for this kind of functionality:

• Some users might want a '--browse'/'--no-browse' (in Homebrew 'CLI::Parser' parlance, which I'll use from here on to keep things shorter, '--[no-]browse') to control whether the command actually opens the destination URL in their browser or simply just prints the URL to their terminal as output.
• All the documentation displayed on https://docs.brew.sh/ is available in users' local installation of Homebrew in '"$(brew --prefix)/docs";' it could (additionally) get rendered to output displayable as 'man' pages.
  • (An additional alternative would be to have invoking the new command spin a local web server up to display the documentation pages, but that would likely be better implemented as an external command.)
• Finally, 'brew help' already exists; does 'brew docs' have to be a separate command? Git handles this by having 'git help' also provide access to 'man' pages that aren't documentation for individual sub-commands.

[jmfayard]

Thanks for the feedback.

I also wondered, since I have never used linuxbrew, whether Linux, which uses a different command, should be supported as well?

Meaning whether it should be the Ruby equivalent of

xdg-open https://docs.brew.sh/ || open https://docs.brew.sh/

Reference: https://linux.die.net/man/1/xdg-open

[jonchang]

utils.rb has exec_browser which commands like brew home use.

[RandomDSdevel]

     As the maintainers would mention/point out, Linuxbrew got merged into Homebrew proper a while back (see Linuxbrew/brew#612, #7028, and the v1.9.0 and v3.3.0 release blog posts for some of the historical details.)

[troymccabe]

Additional thoughts for add-ons:

--list: List all files matching "*.md" (except "README") in $(brew --repo)/docs. Optionally numerically indexed for:
--doc: Either the numeric index or name of a doc in --list. Opens that particular doc.