feat: plugin documentation callback support 🎉 (#757)

docs/plugins-create.md

@@ -57,6 +57,19 @@ If possible the script should only place files in the `ASDF_INSTALL_PATH` direct
 
 ## Optional Scripts
 
+#### bin/help scripts
+
+This is not one callback script but rather a set of callback scripts that each print different documentation to STDOUT. The possible callback scripts are listed below. Note that `bin/help.overview` is a special case as it must be present for any help output to be displayed for the script.
+
+* `bin/help.overview` - This script should output a general description about the plugin and the tool being managed. No heading should be printed as asdf will print headings. Output may be free-form text but ideally only one short paragraph. This script must be present if you want asdf to provide help information for your plugin. All other help callback scripts are optional.
+* `bin/help.deps` - This script should output the list of dependencies tailored to the operating system. One dependency per line.
+* `bin/help.config` - This script should print any required or optional configuration that may be available for the plugin and tool. Any environment variables or other flags needed to install or compile the tool (for the users operating system when possible). Output can be free-form text.
+* `bin/help.links` - This should be a list of links relevant to the plugin and tool (again, tailored to the current operating system when possible). One link per line. Lines may be in the format `<title>: <link>` or just `<link>`.
+
+Each of these scripts should tailor their output to the current operating system. For example, when on Ubuntu the deps script could output the dependencies as apt-get packages that must be installed. The script should also tailor its output to the value of `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE` when the variables are set. They are optional and will not always be set.
+
+The help callback script MUST NOT output any information that is already covered in the core asdf-vm documentation. General asdf usage information must not be present.
+
 #### bin/list-bin-paths
 
 List executables for the specified version of the tool. Must print a string with a space-separated list of dir paths that contain executables. The paths must be relative to the install path passed. Example output would be:

help.txt

@@ -38,6 +38,7 @@ asdf latest <name> [<version>]          Show latest stable version of a package
 asdf list <name>                        List installed versions of a package
 asdf list all <name> [<version>]        List all versions of a package and
                                         optionally filter the returned versions
+asdf help <name> [<version>]            Output documentation for plugin and tool
 
 
 UTILS

lib/commands/command-help.bash

@@ -31,9 +31,84 @@ asdf_extension_cmds() {
 }
 
 help_command() {
-  asdf_help
-  asdf_extension_cmds
-  asdf_moto
+  local plugin_name="$1"
+  local tool_version="$2"
+  local plugin_path
+
+  # If plugin name is present as first argument output plugin help info
+  if [ -n "$plugin_name" ]; then
+    plugin_path=$(get_plugin_path "$plugin_name")
+
+    if [ -d "$plugin_path" ]; then
+      if [ -f "${plugin_path}/bin/help.overview" ]; then
+        if [ -n "$tool_version" ]; then
+
+          # TODO: Refactor this code out into helper functions in utils.bash
+          IFS=':' read -r -a version_info <<<"$tool_version"
+          if [ "${version_info[0]}" = "ref" ]; then
+            local install_type="${version_info[0]}"
+            local version="${version_info[1]}"
+          else
+            local install_type="version"
+
+            if [ "${version_info[0]}" = "latest" ]; then
+              local version
+              version=$(asdf latest "$plugin_name" "${version_info[1]}")
+            else
+              local version="${version_info[0]}"
+            fi
+          fi
+
+          local install_path
+          install_path=$(get_install_path "$plugin_name" "$install_type" "$version")
+
+          (
+            # shellcheck disable=SC2031
+            export ASDF_INSTALL_TYPE=$install_type
+            # shellcheck disable=SC2031
+            export ASDF_INSTALL_VERSION=$version
+            # shellcheck disable=SC2031
+            export ASDF_INSTALL_PATH=$install_path
+
+            print_plugin_help "$plugin_path"
+          )
+        else
+          (print_plugin_help "$plugin_path")
+        fi
+      else
+        echo "No documentation for plugin $plugin_name" >&2
+        exit 1
+      fi
+    else
+      echo "No plugin named $plugin_name" >&2
+      exit 1
+    fi
+  else
+    # Otherwise output general asdf help
+    asdf_help
+    asdf_extension_cmds
+    asdf_moto
+  fi
+}
+
+print_plugin_help() {
+  local plugin_path=$1
+
+  # Eventually @jthegedus or someone else will format the output from these
+  # scripts in a certain way.
+  bash "${plugin_path}"/bin/help.overview
+
+  if [ -f "${plugin_path}"/bin/help.deps ]; then
+    bash "${plugin_path}"/bin/help.deps
+  fi
+
+  if [ -f "${plugin_path}"/bin/help.config ]; then
+    bash "${plugin_path}"/bin/help.config
+  fi
+
+  if [ -f "${plugin_path}"/bin/help.links ]; then
+    bash "${plugin_path}"/bin/help.links
+  fi
 }
 
 help_command "$@"

test/fixtures/dummy_plugin/bin/help.overview

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+echo "Dummy plugin documentation"
+echo
+echo "Dummy plugin is a plugin only used for unit tests"
+
+if [ -n "$ASDF_INSTALL_VERSION" ]; then
+  echo
+  echo "Details specific for version $ASDF_INSTALL_VERSION"
+fi

test/help_command.bats

@@ -0,0 +1,76 @@
+#!/usr/bin/env bats
+
+load test_helpers
+
+setup() {
+  setup_asdf_dir
+  install_dummy_plugin
+  install_dummy_legacy_plugin
+  run asdf install dummy 1.0
+  run asdf install dummy 1.1
+
+  PROJECT_DIR=$HOME/project
+  mkdir $PROJECT_DIR
+}
+
+teardown() {
+  clean_asdf_dir
+}
+
+@test "help should show dummy plugin help" {
+  cd $PROJECT_DIR
+
+  run asdf help "dummy"
+
+  expected_output="$(cat <<EOF
+Dummy plugin documentation
+
+Dummy plugin is a plugin only used for unit tests
+EOF
+)"
+  [ "$status" -eq 0 ]
+  [ "$output" = "$expected_output" ]
+}
+
+@test "help should show dummy plugin help specific to version when version is present" {
+  cd $PROJECT_DIR
+
+  run asdf help "dummy" "1.2.3"
+
+  expected_output="$(cat <<EOF
+Dummy plugin documentation
+
+Dummy plugin is a plugin only used for unit tests
+
+Details specific for version 1.2.3
+EOF
+)"
+  [ "$status" -eq 0 ]
+  echo $output
+  [ "$output" = "$expected_output" ]
+}
+
+@test "help should fail for unknown plugins" {
+  cd $PROJECT_DIR
+
+  run asdf help "sunny"
+  [ "$status" -eq 1 ]
+  [ "$output" == "No plugin named sunny" ]
+}
+
+@test "help should fail when plugin doesn't have documentation callback" {
+  cd $PROJECT_DIR
+
+  run asdf help "legacy-dummy"
+  [ "$status" -eq 1 ]
+  [ "$output" == "No documentation for plugin legacy-dummy" ]
+}
+
+@test "help should show asdf help when no plugin name is provided" {
+  cd $PROJECT_DIR
+
+  run asdf help
+
+  [ "$status" -eq 0 ]
+  # TODO: Assert asdf help output is printed
+}