Merge pull request #3932 from MikeMcQuaid/external-commands-docs

Improve external command documentation

Library/Homebrew/cmd/help.rb

@@ -74,14 +74,13 @@ module Homebrew
   end
 
   def command_help(path)
-    help_lines = path.read.lines.grep(/^#:/)
+    help_lines = command_help_lines(path)
     if help_lines.empty?
       opoo "No help text in: #{path}" if ARGV.homebrew_developer?
       HOMEBREW_HELP
     else
       help_lines.map do |line|
-        line.slice(2..-1)
+        line.sub(/^  \* /, "#{Tty.bold}brew#{Tty.reset} ")
-            .sub(/^  \* /, "#{Tty.bold}brew#{Tty.reset} ")
             .gsub(/`(.*?)`/, "#{Tty.bold}\\1#{Tty.reset}")
             .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
             .gsub(/<(.*?)>/, "#{Tty.underline}\\1#{Tty.reset}")

Library/Homebrew/dev-cmd/man.rb

@@ -71,6 +71,9 @@ module Homebrew
     variables[:former_maintainers] = readme.read[/(Former maintainers .*\.)/, 1]
                                            .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
 
+    variables[:homebrew_bundle] = help_output(:bundle)
+    variables[:homebrew_services] = help_output(:services)
+
     ERB.new(template, nil, ">").result(variables.instance_eval { binding })
   end
 
@@ -113,6 +116,12 @@ module Homebrew
     end
   end
 
+  def help_output(command)
+    tap = Tap.fetch("Homebrew/homebrew-#{command}")
+    tap.install unless tap.installed?
+    command_help_lines(which("brew-#{command}.rb", Tap.cmd_directories))
+  end
+
   def target_path_to_format(target)
     case target.basename
     when /\.md$/    then ["--markdown", "markdown"]

Library/Homebrew/manpages/brew.1.md.erb

@@ -56,17 +56,21 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 ## OFFICIAL EXTERNAL COMMANDS
 
-  * `bundle`:
+  <%= homebrew_bundle.join("\n  ").strip %>
-    Bundler for non-Ruby dependencies from Homebrew:
-    <https://github.com/Homebrew/homebrew-bundle>
 
-  * `cask`:
-    Install macOS applications distributed as binaries:
-    <https://github.com/caskroom/homebrew-cask>
 
-  * `services`:
+  Homebrew/homebrew-bundle <https://github.com/Homebrew/homebrew-bundle>
-    Integrates Homebrew formulae with macOS's `launchctl`(1) manager:
+
-    <https://github.com/Homebrew/homebrew-services>
+  * `cask` [`--version` | `audit` | `cat` | `cleanup` | `create` | `doctor` | `edit` | `fetch` | `home` | `info`]:
+    Install macOS applications distributed as binaries.
+
+
+  Caskroom/homebrew-cask <https://github.com/caskroom/homebrew-cask>
+
+  <%= homebrew_services.join("\n  ").strip %>
+
+
+  Homebrew/homebrew-services <https://github.com/Homebrew/homebrew-services>
 
 ## CUSTOM EXTERNAL COMMANDS
 

Library/Homebrew/utils.rb

@@ -572,3 +572,7 @@ def tap_and_name_comparison
     end
   end
 end
+
+def command_help_lines(path)
+  path.read.lines.grep(/^#:/).map { |line| line.slice(2..-1) }
+end

docs/Manpage.md

@@ -909,17 +909,137 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
 ## OFFICIAL EXTERNAL COMMANDS
 
-  * `bundle`:
+  * `bundle` `command`:
-    Bundler for non-Ruby dependencies from Homebrew:
-    <https://github.com/Homebrew/homebrew-bundle>
 
-  * `cask`:
+      Bundler for non-Ruby dependencies from Homebrew.
-    Install macOS applications distributed as binaries:
-    <https://github.com/caskroom/homebrew-cask>
 
-  * `services`:
+  
-    Integrates Homebrew formulae with macOS's `launchctl`(1) manager:
+
-    <https://github.com/Homebrew/homebrew-services>
+      `bundle` [`install`] [`-v`|`--verbose`] [`--no-upgrade`] [`--file=``path`|`--global`]:
+
+      Install or upgrade all dependencies in a Brewfile.
+
+  
+
+      `brew bundle dump` [`--force`] [`--describe`] [`--file=``path`|`--global`]
+
+      Write all installed casks/formulae/taps into a Brewfile.
+
+  
+
+      `brew bundle cleanup` [`--force`] [`--zap`] [`--file=``path`|`--global`]
+
+      Uninstall all dependencies not listed in a Brewfile.
+
+  
+
+      `brew bundle check` [`--no-upgrade`] [`--file`=`path`|`--global`]
+
+      Check if all dependencies are installed in a Brewfile.
+
+  
+
+      `brew bundle exec` `command`
+
+      Run an external command in an isolated build environment.
+
+  
+
+      `brew bundle list` [`--all`|`--brews`|`--casks`|`--taps`|`--mas`] [`--file=``path`|`--global`]
+
+      List all dependencies present in a Brewfile, optionally limiting by types.
+
+      By default, only brew dependencies are output.
+
+  
+
+      If `-v` or `--verbose` are passed, print verbose output.
+
+  
+
+      If `--no-upgrade` is passed, don't run `brew upgrade` outdated dependencies.
+
+      Note they may still be upgraded by `brew install` if needed.
+
+  
+
+      If `--force` is passed, uninstall dependencies or overwrite an existing Brewfile.
+
+  
+
+      If `--file=`path is passed, the Brewfile path is set accordingly
+
+      Use `--file=-` to output to console.
+
+  
+
+      If `--global` is passed, set Brewfile path to `$HOME/.Brewfile`.
+
+  
+
+      If `--describe` is passed, output a description comment above each line.
+
+      This comment will not be output if the dependency does not have a description.
+
+  
+
+      If `-h` or `--help` are passed, print this help message and exit.
+
+  Homebrew/homebrew-bundle <https://github.com/Homebrew/homebrew-bundle>
+
+  * `cask` [`--version` | `audit` | `cat` | `cleanup` | `create` | `doctor` | `edit` | `fetch` | `home` | `info`]:
+    Install macOS applications distributed as binaries.
+
+
+  Caskroom/homebrew-cask <https://github.com/caskroom/homebrew-cask>
+
+  * `services` `command`:
+
+      Integrates Homebrew formulae with macOS' `launchctl` manager.
+
+  
+
+      [`sudo`] `brew services list`
+
+      List all running services for the current user (or `root`)
+
+  
+
+      [`sudo`] `brew services run` `formula|--all`
+
+      Run the service `formula` without starting at login (or boot).
+
+  
+
+      [`sudo`] `brew services` `start` `formula|--all`
+
+      Start the service `formula` immediately and register it to launch at login (or `boot`).
+
+  
+
+      [`sudo`] `brew services` `stop` `formula|--all`
+
+      Stop the service `formula` immediately and unregister it from launching at login (or `boot`).
+
+  
+
+      [`sudo`] `brew services` `restart` `formula|--all`
+
+      Stop (if necessary) and start the service immediately and register it to launch at login (or `boot`).
+
+  
+
+      [`sudo`] `brew services` `cleanup`
+
+      Remove all unused services.
+
+  
+
+      If `sudo` is passed, operate on `/Library/LaunchDaemons` (started at boot).
+
+      Otherwise, operate on `~/Library/LaunchAgents (started at login)`.
+
+  Homebrew/homebrew-services <https://github.com/Homebrew/homebrew-services>
 
 ## CUSTOM EXTERNAL COMMANDS
 

manpages/brew.1

@@ -930,16 +930,140 @@ If \fB\-\-keep\-tmp\fR is passed, retain the temporary directory containing the
 .SH "OFFICIAL EXTERNAL COMMANDS"
 .
 .TP
-\fBbundle\fR
+\fBbundle\fR \fIcommand\fR:
-Bundler for non\-Ruby dependencies from Homebrew: \fIhttps://github\.com/Homebrew/homebrew\-bundle\fR
+.
+.IP
+Bundler for non\-Ruby dependencies from Homebrew\.
+.
+.IP
+\fBbundle\fR [\fBinstall\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-\-no\-upgrade\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR]:
+.
+.IP
+Install or upgrade all dependencies in a Brewfile\.
+.
+.IP
+\fBbrew bundle dump\fR [\fB\-\-force\fR] [\fB\-\-describe\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR]
+.
+.IP
+Write all installed casks/formulae/taps into a Brewfile\.
+.
+.IP
+\fBbrew bundle cleanup\fR [\fB\-\-force\fR] [\fB\-\-zap\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR]
+.
+.IP
+Uninstall all dependencies not listed in a Brewfile\.
+.
+.IP
+\fBbrew bundle check\fR [\fB\-\-no\-upgrade\fR] [\fB\-\-file\fR=\fIpath\fR|\fB\-\-global\fR]
+.
+.IP
+Check if all dependencies are installed in a Brewfile\.
+.
+.IP
+\fBbrew bundle exec\fR \fIcommand\fR
+.
+.IP
+Run an external command in an isolated build environment\.
+.
+.IP
+\fBbrew bundle list\fR [\fB\-\-all\fR|\fB\-\-brews\fR|\fB\-\-casks\fR|\fB\-\-taps\fR|\fB\-\-mas\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR]
+.
+.IP
+List all dependencies present in a Brewfile, optionally limiting by types\.
+.
+.IP
+By default, only brew dependencies are output\.
+.
+.IP
+If \fB\-v\fR or \fB\-\-verbose\fR are passed, print verbose output\.
+.
+.IP
+If \fB\-\-no\-upgrade\fR is passed, don\'t run \fBbrew upgrade\fR outdated dependencies\.
+.
+.IP
+Note they may still be upgraded by \fBbrew install\fR if needed\.
+.
+.IP
+If \fB\-\-force\fR is passed, uninstall dependencies or overwrite an existing Brewfile\.
+.
+.IP
+If \fB\-\-file=<path>\fR is passed, the Brewfile path is set accordingly
+.
+.IP
+Use \fB\-\-file=\-\fR to output to console\.
+.
+.IP
+If \fB\-\-global\fR is passed, set Brewfile path to \fB$HOME/\.Brewfile\fR\.
+.
+.IP
+If \fB\-\-describe\fR is passed, output a description comment above each line\.
+.
+.IP
+This comment will not be output if the dependency does not have a description\.
+.
+.IP
+If \fB\-h\fR or \fB\-\-help\fR are passed, print this help message and exit\.
+.
+.P
+Homebrew/homebrew\-bundle \fIhttps://github\.com/Homebrew/homebrew\-bundle\fR
 .
 .TP
-\fBcask\fR
+\fBcask\fR [\fB\-\-version\fR | \fBaudit\fR | \fBcat\fR | \fBcleanup\fR | \fBcreate\fR | \fBdoctor\fR | \fBedit\fR | \fBfetch\fR | \fBhome\fR | \fBinfo\fR]
-Install macOS applications distributed as binaries: \fIhttps://github\.com/caskroom/homebrew\-cask\fR
+Install macOS applications distributed as binaries\.
+.
+.P
+Caskroom/homebrew\-cask \fIhttps://github\.com/caskroom/homebrew\-cask\fR
 .
 .TP
-\fBservices\fR
+\fBservices\fR \fIcommand\fR:
-Integrates Homebrew formulae with macOS\'s \fBlaunchctl\fR(1) manager: \fIhttps://github\.com/Homebrew/homebrew\-services\fR
+.
+.IP
+Integrates Homebrew formulae with macOS\' \fBlaunchctl\fR manager\.
+.
+.IP
+[\fIsudo\fR] \fBbrew services list\fR
+.
+.IP
+List all running services for the current user (or \fIroot\fR)
+.
+.IP
+[\fIsudo\fR] \fBbrew services run\fR \fIformula|\-\-all\fR
+.
+.IP
+Run the service \fIformula\fR without starting at login (or boot)\.
+.
+.IP
+[\fIsudo\fR] \fBbrew services\fR \fBstart\fR \fIformula|\-\-all\fR
+.
+.IP
+Start the service \fIformula\fR immediately and register it to launch at login (or \fIboot\fR)\.
+.
+.IP
+[\fIsudo\fR] \fBbrew services\fR \fBstop\fR \fIformula|\-\-all\fR
+.
+.IP
+Stop the service \fIformula\fR immediately and unregister it from launching at login (or \fIboot\fR)\.
+.
+.IP
+[\fIsudo\fR] \fBbrew services\fR \fBrestart\fR \fIformula|\-\-all\fR
+.
+.IP
+Stop (if necessary) and start the service immediately and register it to launch at login (or \fIboot\fR)\.
+.
+.IP
+[\fIsudo\fR] \fBbrew services\fR \fBcleanup\fR
+.
+.IP
+Remove all unused services\.
+.
+.IP
+If \fBsudo\fR is passed, operate on \fB/Library/LaunchDaemons\fR (started at boot)\.
+.
+.IP
+Otherwise, operate on \fB~/Library/LaunchAgents (started at login)\fR\.
+.
+.P
+Homebrew/homebrew\-services \fIhttps://github\.com/Homebrew/homebrew\-services\fR
 .
 .SH "CUSTOM EXTERNAL COMMANDS"
 Homebrew, like \fBgit\fR(1), supports external commands\. These are executable scripts that reside somewhere in the \fBPATH\fR, named \fBbrew\-\fR\fIcmdname\fR or \fBbrew\-\fR\fIcmdname\fR\fB\.rb\fR, which can be invoked like \fBbrew\fR \fIcmdname\fR\. This allows you to create your own commands without modifying Homebrew\'s internals\.