import rbenv-help from rbenv 0.4.0

libexec/pyenv-commands

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List all available pyenv commands
+# Usage: pyenv commands [--sh|--no-sh]
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-completions

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
+# Usage: pyenv completions <command> [arg1 arg2...]
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
 COMMAND="$1"
 if [ -z "$COMMAND" ]; then
-  echo "usage: pyenv completions COMMAND [arg1 arg2...]" >&2
+  pyenv-help --usage completions >&2
   exit 1
 fi
 

libexec/pyenv-exec

@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Run an executable with the selected Python version
+#
+# Usage: pyenv exec <command> [arg1 arg2...]
+#
+# Runs an executable by first preparing PATH so that the selected Python
+# version's `bin' directory is at the front.
+#
+# For example, if the currently selected Python version is 2.7.7:
+#   pyenv exec pip install -rrequirements.txt
+#
+# is equivalent to:
+#   PATH="$PYENV_ROOT/versions/2.7.7/bin:$PATH" pip install -rrequirements.txt
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
@@ -8,8 +22,9 @@ if [ "$1" = "--complete" ]; then
 fi
 
 PYENV_COMMAND="$1"
+
 if [ -z "$PYENV_COMMAND" ]; then
-  echo "usage: pyenv exec COMMAND [arg1 arg2...]" >&2
+  pyenv-help --usage exec >&2
   exit 1
 fi
 

libexec/pyenv-global

@@ -1,4 +1,17 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the global Python version
+#
+# Usage: pyenv global <version>
+#
+# Sets the global Python version. You can override the global version at
+# any time by setting a directory-specific version with `pyenv local'
+# or by setting the `PYENV_VERSION' environment variable.
+#
+# <version> should be a string matching a Python version known to pyenv.
+# The special version string `system' will use your default system Python.
+# Run `pyenv versions' for a list of available Python versions.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-help

@@ -1,99 +1,162 @@
 #!/usr/bin/env bash
+#
+# Summary: Display help for a command
+#
+# Usage: pyenv help [--usage] COMMAND
+#
+# Parses and displays help contents from a command's source file.
+#
+# A command is considered documented if it starts with a comment block
+# that has a `Summary:' or `Usage:' section. Usage instructions can
+# span multiple lines as long as subsequent lines are indented.
+# The remainder of the comment block is displayed as extended
+# documentation.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
-print_set_version() {
-  echo "<version> should be a string matching a Python version known by pyenv."
+command_path() {
+  local command="$1"
+  command -v pyenv-"$command" || command -v pyenv-sh-"$command" || true
+}
+
+extract_initial_comment_block() {
+  sed -ne "
+    /^#/ !{
+      q
+    }
+
+    s/^#$/# /
+
+    /^# / {
+      s/^# //
+      p
+    }
+  "
+}
+
+collect_documentation() {
+  awk '
+    /^Summary:/ {
+      summary = substr($0, 10)
+      next
+    }
+
+    /^Usage:/ {
+      reading_usage = 1
+      usage = usage "\n" $0
+      next
+    }
+
+    /^( *$|       )/ && reading_usage {
+      usage = usage "\n" $0
+      next
+    }
+
+    {
+      reading_usage = 0
+      help = help "\n" $0
+    }
+
+    function escape(str) {
+      gsub(/[`\\$"]/, "\\\\&", str)
+      return str
+    }
+
+    function trim(str) {
+      gsub(/^\n*/, "", str)
+      gsub(/\n*$/, "", str)
+      return str
+    }
+
+    END {
+      if (usage || summary) {
+        print "summary=\"" escape(summary) "\""
+        print "usage=\"" escape(trim(usage)) "\""
+        print "help=\"" escape(trim(help)) "\""
+      }
+    }
+  '
+}
+
+documentation_for() {
+  local filename="$(command_path "$1")"
+  if [ -n "$filename" ]; then
+    extract_initial_comment_block < "$filename" | collect_documentation
+  fi
+}
+
+print_summary() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+
+  if [ -n "$summary" ]; then
+    printf "   %-9s   %s\n" "$command" "$summary"
+  fi
+}
+
+print_summaries() {
+  for command; do
+    print_summary "$command"
+  done
+}
 
-  local versions="$(pyenv-versions --bare)"
-  if [ -z "$versions" ]; then
-    echo "There are currently no Python versions installed for pyenv."
+print_help() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+  [ -n "$help" ] || help="$summary"
+
+  if [ -n "$usage" -o -n "$summary" ]; then
+    if [ -n "$usage" ]; then
+      echo "$usage"
+    else
+      echo "Usage: pyenv ${command}"
+    fi
+    if [ -n "$help" ]; then
+      echo
+      echo "$help"
+      echo
+    fi
   else
-    echo "The currently installed Python versions are:"
-    echo "$versions" | sed 's/^/  /'
+    echo "Sorry, this command isn't documented yet." >&2
+    return 1
   fi
+}
 
-  echo
-  echo "The special version string 'system' will use your default system Python"
+print_usage() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+  [ -z "$usage" ] || echo "$usage"
 }
 
-case "$1" in
-"") echo "usage: pyenv <command> [<args>]
-
-Some useful pyenv commands are:
-   commands      List all pyenv commands
-   rehash        Rehash pyenv shims (run this after installing binaries)
-   global        Set or show the global Python version
-   local         Set or show the local directory-specific Python version
-   shell         Set or show the shell-specific Python version
-   version       Show the current Python version
-   versions      List all Python versions known by pyenv
-   which         Show the full path for the given Python command
-   whence        List all Python versions with the given command
-
-See 'pyenv help <command>' for information on a specific command.
-For full documentation, see: https://github.com/yyuu/pyenv#readme"
-;;
-commands) echo "usage: pyenv commands
-       pyenv commands --sh
-       pyenv commands --no-sh
-
-List all pyenv commands."
-;;
-global) echo "usage: pyenv global <version>
-
-Sets the global Python version. You can override the global version at
-any time by setting a directory-specific version with \`pyenv local'
-or by setting the PYENV_VERSION environment variable.
-
-$(print_set_version)"
-;;
-local) echo "usage: pyenv local <version>
-       pyenv local --unset
-
-Sets the local directory-specific Python version by writing the version
-name to a file named '.pyenv-version'.
-
-When you run a Python command, pyenv will look for an '.pyenv-version'
-file in the current directory and each parent directory. If no such
-file is found in the tree, pyenv will use the global Python version
-specified with \`pyenv global', or the version specified in the
-PYENV_VERSION environment variable.
-
-$(print_set_version)"
-;;
-shell) echo "usage: pyenv shell <version>
-       pyenv shell --unset
-
-Sets a shell-specific Python version by setting the 'PYENV_VERSION'
-environment variable in your shell. This version overrides both
-project-specific versions and the global version.
-
-$(print_set_version)"
-;;
-versions) echo "usage: pyenv versions
-       pyenv versions --bare
-
-Lists all Python versions known by pyenv."
-;;
-which) echo "usage: pyenv which <command>
-
-Displays the full path to the binary that pyenv will execute when you
-run the given command."
-;;
-whence) echo "usage: pyenv whence <command>
-
-Lists all Python versions with the given command installed."
-;;
-*)
-  command_path="$(command -v "pyenv-$1" || true)"
-  if [ -n "$command_path" ]; then
-    echo "Sorry, the \`$1' command isn't documented yet."
-    echo
-    echo "You can view the command's source here:"
-    echo "$command_path"
-    echo
+unset usage
+if [ "$1" = "--usage" ]; then
+  usage="1"
+  shift
+fi
+
+if [ -z "$1" ] || [ "$1" == "pyenv" ]; then
+  echo "Usage: pyenv <command> [<args>]"
+  [ -z "$usage" ] || exit
+  echo
+  echo "Some useful pyenv commands are:"
+  print_summaries commands local global shell install uninstall rehash version versions which whence
+  echo
+  echo "See \`pyenv help <command>' for information on a specific command."
+  echo "For full documentation, see: https://github.com/yyuu/pyenv#readme"
+else
+  command="$1"
+  if [ -n "$(command_path "$command")" ]; then
+    if [ -n "$usage" ]; then
+      print_usage "$command"
+    else
+      print_help "$command"
+    fi
   else
-    echo "pyenv: no such command \`$1'"
+    echo "pyenv: no such command \`$command'" >&2
+    exit 1
   fi
-esac
+fi

libexec/pyenv-hooks

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List hook scripts for a given pyenv command
+# Usage: pyenv hooks <command>
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
@@ -12,7 +15,7 @@ fi
 
 PYENV_COMMAND="$1"
 if [ -z "$PYENV_COMMAND" ]; then
-  echo "usage: pyenv hooks COMMAND" >&2
+  pyenv-help --usage hooks >&2
   exit 1
 fi
 

libexec/pyenv-init

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: Configure the shell environment for pyenv
+# Usage: eval "$(pyenv init - [--no-rehash] [<shell>])"
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-local

@@ -1,4 +1,28 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the local application-specific Python version
+#
+# Usage: pyenv local <version>
+#        pyenv local --unset
+#
+# Sets the local application-specific Python version by writing the
+# version name to a file named `.python-version'.
+#
+# When you run a Python command, pyenv will look for a `.python-version'
+# file in the current directory and each parent directory. If no such
+# file is found in the tree, pyenv will use the global Python version
+# specified with `pyenv global'. A version specified with the
+# `PYENV_VERSION' environment variable takes precedence over local
+# and global versions.
+#
+# For backwards compatibility, pyenv will also read version
+# specifications from `.pyenv-version' files, but a `.python-version'
+# file in the same directory takes precedence.
+#
+# <version> should be a string matching a Python version known to pyenv.
+# The special version string `system' will use your default system Python.
+# Run `pyenv versions' for a list of available Python versions.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-prefix

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+# Summary: Display prefix for a Python version
+# Usage: pyenv prefix [<version>]
+#
+# Displays the directory where a Python version is installed. If no
+# version is given, `pyenv prefix' displays the location of the
+# currently selected version.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-rehash

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Summary: Rehash pyenv shims (run this after installing executables)
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-root

@@ -1,2 +1,3 @@
 #!/usr/bin/env bash
+# Summary: Display the root directory where versions and shims are kept
 echo $PYENV_ROOT

libexec/pyenv-sh-pop

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Usage: pyenv pop <version>
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-sh-push

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Usage: pyenv push <version>
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-sh-shell

@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the shell-specific Python version
+#
+# Usage: pyenv shell <version>
+#        pyenv shell --unset
+#
+# Sets a shell-specific Python version by setting the `PYENV_VERSION'
+# environment variable in your shell. This version overrides local
+# application-specific versions and the global version.
+#
+# <version> should be a string matching a Python version known to pyenv.
+# The special version string `system' will use your default system Python.
+# Run `pyenv versions' for a list of available Python versions.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-shims

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List existing pyenv shims
+# Usage: pyenv shims [--short]
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-version

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+# Summary: Show the current Python version and its origin
+#
+# Shows the currently selected Python version and how it was
+# selected. To obtain only the version string, use `pyenv
+# version-name'.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-version-file

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Detect the file that sets the current pyenv version
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-version-file-read

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Usage: pyenv version-file-read <file>
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-version-file-write

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: pyenv version-file-write <file> <version>
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
@@ -7,7 +9,7 @@ shift
 versions=("$@")
 
 if [ -z "$versions" ] || [ -z "$PYENV_VERSION_FILE" ]; then
-  echo "usage: pyenv write-version-file FILENAME VERSIONS..." >&2
+  pyenv-help --usage version-file-write >&2
   exit 1
 fi
 

libexec/pyenv-version-name

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Show the current Python version
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-version-origin

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Explain how the current Python version is set
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-versions

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# Summary: List all Python versions available to pyenv
+# Usage: pyenv versions [--bare]
+#
+# Lists all Python versions found in `$PYENV_ROOT/versions/*'.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 

libexec/pyenv-whence

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List all Python versions that contain the given executable
+# Usage: pyenv whence [--path] <command>
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
@@ -27,7 +30,7 @@ whence() {
 
 PYENV_COMMAND="$1"
 if [ -z "$PYENV_COMMAND" ]; then
-  echo "usage: pyenv whence [--path] COMMAND" >&2
+  pyenv-help --usage whence >&2
   exit 1
 fi
 

libexec/pyenv-which

@@ -1,4 +1,12 @@
 #!/usr/bin/env bash
+#
+# Summary: Display the full path to an executable
+#
+# Usage: pyenv which <command>
+#
+# Displays the full path to the executable that pyenv will invoke when
+# you run the given command.
+
 set -e
 [ -n "$PYENV_DEBUG" ] && set -x
 
@@ -45,7 +53,7 @@ IFS=: PYENV_VERSION="${versions[*]}"
 PYENV_COMMAND="$1"
 
 if [ -z "$PYENV_COMMAND" ]; then
-  echo "usage: pyenv which COMMAND" >&2
+  pyenv-help --usage which >&2
   exit 1
 fi