Collapse help into expandable command topics

docs/development/plugin-creation.md

@@ -75,11 +75,30 @@ hello/commands
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
-  help)
+  help | hello:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     hello <app>, Says "Hello <app>"
     hello:world, Says "Hello world"
-EOF
+help_content
+    }
+
+    if [[ $1 = "hello:help" ]] ; then
+        echo -e 'Usage: dokku hello[:world] [<app>]'
+        echo ''
+        echo 'Say Hello World.'
+        echo ''
+        echo 'Example:'
+        echo ''
+        echo '$ dokku hello:world'
+        echo 'Hello world'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

docs/development/plugin-triggers.md

@@ -92,10 +92,10 @@ cd /root/dokku
 sudo BUILD_STACK=true make install
 ```
 
-### `commands help`
+### `comands help` and `commands <PLUGIN_NAME>:help`
 
-- Description: Used to aggregate all plugin `help` output. Your plugin should implement a `help` command in your `commands` file to take advantage of this plugin trigger. This must be implemented inside the `commands` plugin file.
+- Description: Your plugin should implement a `help` command in your `commands` file to take advantage of this plugin trigger. `commands help` is used by `dokku help` to aggregate all plugins abbreviated `help` output. Implementing  `<PLUGIN_NAME>:help` in your `commands` file gives users looking for help, a more detailed output. 'commands help' must be implemented inside the `commands` plugin file. It's recommended that `PLUGIN_NAME:help` be added to the commands file to ensure consistency among community plugins and give you a new avenue to share rich help content with your user.
-- Invoked by: `dokku help`
+- Invoked by: `dokku help` and `commands <PLUGIN_NAME>:help`
 - Arguments: None
 - Example:
 
@@ -106,11 +106,30 @@ sudo BUILD_STACK=true make install
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
-  help | derp:help)
+  help | hello:help)
-    cat<<EOF
+    help_content_func () {
-    derp:herp, Herps the derp
+      declare desc="return help_content string"
-    derp:serp [file], Shows the file's serp
+      cat<<help_content
-EOF
+    hello <app>, Says "Hello <app>"
+    hello:world, Says "Hello world"
+help_content
+    }
+
+    if [[ $1 = "hello:help" ]] ; then
+        echo -e 'Usage: dokku hello[:world] [<app>]'
+        echo ''
+        echo 'Say Hello World.'
+        echo ''
+        echo 'Example:'
+        echo ''
+        echo '$ dokku hello:world'
+        echo 'Hello world'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

docs/docker-options.md

@@ -5,8 +5,7 @@
 Pass [options](https://docs.docker.com/engine/reference/run/) to Docker during Dokku's `build`, `deploy` and `run` phases
 
 ```
-docker-options <app>                             Display app's Docker options for all phases
+docker-options <app> [phase(s)]                  Display app's Docker options for all phases (or comma separated phase list)
-docker-options <app> <phase(s)>                  Display app's Docker options for phase (comma-separated phase list)
 docker-options:add <app> <phase(s)> OPTION       Add Docker option to app for phase (comma-separated phase list)
 docker-options:remove <app> <phase(s)> OPTION    Remove Docker option from app for phase (comma-separated phase list)
 ```

dokku

@@ -157,13 +157,54 @@ execute_dokku_cmd() {
 
 case "$1" in
   help|'')
+    export LC_ALL=C # so sort will respect non alpha characters
+    ALL_PLUGIN_COMMANDS=$(find -L "$PLUGIN_PATH/enabled" -name commands 2> /dev/null || true)
+
+    # build list of core plugin command files
+    for plugin_command in $ALL_PLUGIN_COMMANDS;do
+      if [[ "$(readlink -f "$plugin_command")" == *core-plugins* ]]; then
+        CORE_PLUGIN_COMMANDS+="$plugin_command "
+      fi
+    done
+    # build list of non-core plugin command files
+    for plugin_command in $ALL_PLUGIN_COMMANDS;do
+      if [[ "$(readlink -f "$plugin_command")" != *core-plugins* ]]; then
+        COMMUNITY_PLUGIN_COMMANDS+="$plugin_command "
+      fi
+    done
+
+    # New lines are blank echos for readability
     echo "Usage: dokku [--quiet|--trace|--rm-container|--rm|--force] COMMAND <app> [command-specific-options]"
     echo ""
-    echo "Options:"
+    echo "Primary help options, type \"dokku COMMAND:help\" for more details, or dokku help --all to see all commands."
+    echo ""
+    echo "Commands:"
+    echo ""
 
-    cat<<EOF | plugn trigger commands help | sort | column -c2 -t -s,
+    if [[ "$2" == "--all" ]] ; then
-    help, Print the list of commands
+      for core_plugin_command in $CORE_PLUGIN_COMMANDS; do
-EOF
+        $core_plugin_command help
+      done | sort | column -c2 -t -s,
+      echo ""
+      echo "Community plugin commands:"
+      echo ""
+      for community_plugin_command in $COMMUNITY_PLUGIN_COMMANDS; do
+        $community_plugin_command help
+      done | sort | column -c2 -t -s,
+    else
+      for core_plugin_command in $CORE_PLUGIN_COMMANDS; do
+        $core_plugin_command help
+      # When done, sort, sed cuts arugments out of strings and colum make it pretty
+      done | sort | sed -e '/^.*:/d' -e 's/\s[\[\<\-\(].*,/,/' | column -c2 -t -s,
+      if [[ -n "$COMMUNITY_PLUGIN_COMMANDS" ]]; then
+        echo ""
+        echo "Community plugin commands:"
+        echo ""
+        for community_plugin_command in $COMMUNITY_PLUGIN_COMMANDS; do
+          $community_plugin_command help
+        done | sort | column -c2 -t -s,
+      fi
+    fi
     ;;
 
   *)

plugins/00_dokku-standard/commands

@@ -1,17 +1,28 @@
 #!/usr/bin/env bash
-[[ " help " == *" $1 "* ]] || exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+[[ " help help:help ls:help run:help trace:help url:help urls:help version:help " == *" $1 "* ]] || exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
-  help)
+  help|ls:help|run:help|trace:help|url:help|urls:help|version:help)
-    cat<<EOF
+    [[ $(echo "$1" | sed '/.*:help/!d') ]] && help_topic="${1%\:help}"
-    ls, Pretty listing of deployed applications and containers
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
+    ls , Pretty listing of deployed applications and containers
     run <app> <cmd>, Run a command in the environment of an application
     trace [on/off], Enable dokku tracing
     url <app>, Show the first URL for an application (compatibility)
     urls <app>, Show all URLs for an application
-    version, Print dokku's version
+    version , Print dokku's version
-EOF
+    help , Print the list of commands
+help_content
+    }
+
+    if [[ $help_topic ]] ; then
+        help_content_func | sed "/^\s*$help_topic\s/!d" | sort | sed '/^.*:/d' | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/20_events/commands

@@ -4,12 +4,26 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | events:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     events [-t], Show the last events (-t follows)
     events:list, List logged events
     events:on, Enable events logger
     events:off, Disable events logger
-EOF
+help_content
+    }
+
+    if [[ $1 = "events:help" ]] ; then
+        echo 'Usage: dokku events:COMMAND [-t]'
+        echo ''
+        echo 'Interact with Dokku event logger.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/apps/commands

@@ -4,12 +4,33 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | apps:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     apps, List your apps
     apps:create <app>, Create a new app
     apps:destroy <app>, Permanently destroy an app
     apps:rename <old-app> <new-app>, Rename an app
-EOF
+help_content
+    }
+
+    if [[ $1 = "apps:help" ]] ; then
+        echo -e 'Usage: dokku apps[:COMMAND]'
+        echo ''
+        echo 'List your apps.'
+        echo ''
+        echo 'Example:'
+        echo ''
+        echo '$ dokku apps'
+        echo '=====> My Apps'
+        echo 'example'
+        echo 'example2'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/certs/commands

@@ -4,7 +4,9 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | certs:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     certs:add <app> CRT KEY, Add an ssl endpoint to an app. Can also import from a tarball on stdin
     certs:chain CRT [CRT ...], [NOT IMPLEMENTED] Print the ordered and complete chain for the given certificate.
     certs:generate <app> DOMAIN, Generate a key and certificate signing request (and self-signed certificate)
@@ -13,7 +15,19 @@ case "$1" in
     certs:remove <app>, Remove an SSL Endpoint from an app.
     certs:rollback <app>, [NOT IMPLEMENTED] Rollback an SSL Endpoint for an app.
     certs:update <app> CRT KEY, Update an SSL Endpoint on an app. Can also import from a tarball on stdin
-EOF
+help_content
+    }
+
+    if [[ $1 = "certs:help" ]] ; then
+        echo -e 'Usage: dokku certs:COMMAND'
+        echo ''
+        echo 'Manage Dokku apps SSL (TLS) certs.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/checks/commands

@@ -3,12 +3,26 @@
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
-  help | ps:help)
+  help | checks:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     checks <app>, Show zero-downtime status
     checks:enable <app>, Enable zero-downtime checks
     checks:disable <app>, Disable zero-downtime checks
-EOF
+help_content
+    }
+
+    if [[ $1 = "checks:help" ]] ; then
+        echo -e 'Usage: dokku checks[:COMAND]'
+        echo ''
+        echo 'Manage zero-downtime checks.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/config/commands

@@ -4,12 +4,26 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | config:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     config (<app>|--global), Display all global or app-specific config vars
     config:get (<app>|--global) KEY, Display a global or app-specific config value
     config:set (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...], Set one or more config vars
     config:unset (<app>|--global) KEY1 [KEY2 ...], Unset one or more config vars
-EOF
+help_content
+    }
+
+    if [[ $1 = "config:help" ]] ; then
+        echo -e 'Usage: dokku config[:COMMAND] (<app>|--global)'
+        echo ''
+        echo 'Manage global or app-specific config vars.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/docker-options/commands

@@ -4,12 +4,25 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | docker-options:help)
-    cat<<EOF
+    help_content_func () {
-    docker-options <app>, Display app's Docker options for all phases
+      declare desc="return help_content string"
-    docker-options <app> <phase(s)>, Display app's Docker options for phase (comma separated phase list)
+      cat<<help_content
+    docker-options <app> [phase(s)], Display app's Docker options for all phases (or comma separated phase list)
     docker-options:add <app> <phase(s)> OPTION, Add Docker option to app for phase (comma separated phase list)
     docker-options:remove <app> <phase(s)> OPTION, Remove Docker option from app for phase (comma separated phase list)
-EOF
+help_content
+    }
+
+    if [[ $1 = "docker-options:help" ]] ; then
+        echo -e 'Usage: dokku docker-options[:COMMAND]'
+        echo ''
+        echo 'Display app'"'"'s Docker options for all phases.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
   ;;
 
   *)

plugins/domains/commands

@@ -4,7 +4,9 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | domains:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     domains [<app>], List domains
     domains:add <app> DOMAIN, Add a domain to app
     domains:clear <app>, Clear all domains for app
@@ -12,7 +14,19 @@ case "$1" in
     domains:enable <app>, Enable VHOST support
     domains:remove <app> DOMAIN, Remove a domain from app
     domains:set-global <domain>, Set global domain name
-EOF
+help_content
+    }
+
+    if [[ $1 = "domains:help" ]] ; then
+        echo -e 'Usage: dokku domains[:COMMAND]'
+        echo ''
+        echo 'Manage vhost domains used by the Dokku proxy.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/enter/commands

@@ -4,9 +4,23 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | enter:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     enter <app> [<container-type> || --container-id <container-id>], Connect to a specific app container
-EOF
+help_content
+    }
+
+    if [[ $1 = "enter:help" ]] ; then
+        echo -e 'Usage: dokku enter <app>'
+        echo ''
+        echo 'Allows you to access a bash prompt inside the container of the app.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/nginx-vhosts/commands

@@ -4,11 +4,25 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | nginx:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     nginx:build-config <app>, (Re)builds nginx config for given app
     nginx:access-logs <app> [-t], Show the nginx access logs for an application (-t follows)
     nginx:error-logs <app> [-t], Show the nginx error logs for an application (-t follows)
-EOF
+help_content
+    }
+
+    if [[ $1 = "nginx:help" ]] ; then
+        echo -e 'Usage: dokku nginx[:COMMAND]'
+        echo ''
+        echo 'Interact with Dokkus Nginx proxy.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
   ;;
 
   *)

plugins/plugin/commands

@@ -4,7 +4,9 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | plugin:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     plugin, Print active plugins
     plugin:install [--core|git-url [--committish tag|branch|commit|--name custom-plugin-name]], Optionally download git-url (with custom tag/committish) & run install trigger for active plugins (or only core ones)
     plugin:install-dependencies [--core], Run install-dependencies trigger for active plugins (or only core ones)
@@ -12,7 +14,19 @@ case "$1" in
     plugin:enable <name>, Enable a previously disabled plugin
     plugin:disable <name>, Disable an installed plugin (third-party only)
     plugin:uninstall <name>, Uninstall a plugin (third-party only)
-EOF
+help_content
+    }
+
+    if [[ $1 = "plugin:help" ]] ; then
+        echo -e 'Usage: dokku plugin[:COMMAND]'
+        echo ''
+        echo 'View installed plugins and manage community plugins.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/proxy/commands

@@ -4,12 +4,26 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | proxy:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     proxy <app>, Show proxy for app
     proxy:enable <app>, Enable proxy for app
     proxy:disable <app>, Disable proxy for app
     proxy:set <app> <proxy_type>, NOT IMPLEMENTED YET!!
-EOF
+help_content
+    }
+
+    if [[ $1 = "proxy:help" ]] ; then
+        echo -e 'Usage: dokku proxy[:COMMAND]'
+        echo ''
+        echo 'Control the proxy used by dokku, per app.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/ps/commands

@@ -4,7 +4,9 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | ps:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     ps <app>, List processes running in app container(s)
     ps:scale [<app> <proc>=<count> [<proc>=<count>]], Get/Set how many instances of a given process to run
     ps:start <app>, Start app container(s)
@@ -14,7 +16,19 @@ case "$1" in
     ps:restart <app>, Restart app container(s)
     ps:restartall, Restart all deployed app containers
     ps:restore, Start previously running apps e.g. after reboot
-EOF
+help_content
+    }
+
+    if [[ $1 = "ps:help" ]] ; then
+        echo -e 'Usage: dokku ps[:COMMAND]'
+        echo ''
+        echo 'List running processes in container, and restart app.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/shell/commands

@@ -4,9 +4,25 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | shell:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     shell, Spawn dokku shell
-EOF
+help_content
+    }
+
+    if [[ $1 = "shell:help" ]] ; then
+        echo -e 'Usage: dokku docker-options[:COMMAND]'
+        echo ''
+        echo 'Dokku shell is an interactive dokku prompt.'
+        echo ''
+        echo 'Note: See dokku enter:help for shell access to containers.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/storage/commands

@@ -4,11 +4,25 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | storage:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     storage:list <app>, List bind mounts for app's container(s) (host:container)
     storage:mount <app> <host-dir:container-dir>, Create a new bind mount
     storage:unmount <app> <host-dir:container-dir>, Remove an existing bind mount
-EOF
+help_content
+    }
+
+    if [[ $1 = "shell:help" ]] ; then
+        echo -e 'Usage: dokku storage:COMMAND'
+        echo ''
+        echo 'Mount local volume / directories inside containers.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/tags/commands

@@ -4,12 +4,26 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | tags:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     tags <app>, List all app image tags
     tags:create <app> <tag>, Add tag to latest running app image
     tags:deploy <app> <tag>, Deploy tagged app image
     tags:destroy <app> <tag>, Remove app image tag
-EOF
+help_content
+    }
+
+    if [[ $1 = "tags:help" ]] ; then
+        echo -e 'Usage: dokku tags[:COMMAND]'
+        echo ''
+        echo 'Manage docker image tags.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)

plugins/tar/commands

@@ -4,10 +4,24 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 case "$1" in
   help | tar:help)
-    cat<<EOF
+    help_content_func () {
+      declare desc="return help_content string"
+      cat<<help_content
     tar:in <app>, Reads an tarball containing the app from stdin
     tar:from <app> <url>, Loads an app tarball from url.
-EOF
+help_content
+    }
+
+    if [[ $1 = "tar:help" ]] ; then
+        echo -e 'Usage: dokku tar[:COMMAND]'
+        echo ''
+        echo 'An alternative to using git, apps are loaded via tarballs instead.'
+        echo ''
+        echo 'Additional commands:'
+        help_content_func | sort | column -c2 -t -s,
+    else
+        help_content_func
+    fi
     ;;
 
   *)