[ADD] DCOS-1323

[FIX] add new line

[FIX] change check

cli/dcoscli/common.py

@@ -0,0 +1,28 @@
+import subprocess
+
+
+def exec_command(cmd, env=None, stdin=None):
+    """Execute CLI command
+
+    :param cmd: Program and arguments
+    :type cmd: [str]
+    :param env: Environment variables
+    :type env: dict
+    :param stdin: File to use for stdin
+    :type stdin: file
+    :returns: A tuple with the returncode, stdout and stderr
+    :rtype: (int, bytes, bytes)
+    """
+
+    process = subprocess.Popen(
+        cmd,
+        stdin=stdin,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env)
+
+    # This is needed to get rid of '\r' from Windows's lines endings.
+    stdout, stderr = [std_stream.replace(b'\r', b'')
+                      for std_stream in process.communicate()]
+
+    return (process.returncode, stdout, stderr)

cli/dcoscli/help/main.py

@@ -1,8 +1,9 @@
 """Display command line usage information
 
 Usage:
-    dcos help --info
     dcos help
+    dcos help --info
+    dcos help <command>
 
 Options:
     --help     Show this screen
@@ -15,6 +16,7 @@ import docopt
 from concurrent.futures import ThreadPoolExecutor
 from dcos import cmds, emitting, options, subcommand, util
 from dcos.errors import DCOSException
+from dcoscli.common import exec_command
 from dcoscli.main import decorate_docopt_usage
 
 emitter = emitting.FlatEmitter()
@@ -47,34 +49,72 @@ def _cmds():
     """
 
     return [
+        cmds.Command(
+            hierarchy=['help', '--info'],
+            arg_keys=[],
+            function=_info),
+
         cmds.Command(
             hierarchy=['help'],
-            arg_keys=['--info'],
+            arg_keys=['<command>'],
             function=_help),
     ]
 
 
-def _help(show_info):
+def _info():
-    if show_info:
+    """
-        emitter.publish(__doc__.split('\n')[0])
+    :returns: process return code
+    :rtype: int
+    """
+
+    emitter.publish(__doc__.split('\n')[0])
+    return 0
+
+
+def _help(command):
+    """
+    :param command: the command name for which you want to see a help
+    :type command: str
+    :returns: process return code
+    :rtype: int
+    """
+
+    if command is not None:
+        _help_command(command)
+    else:
+        directory = util.dcos_path()
+        logger.debug("DCOS Path: {!r}".format(directory))
+
+        paths = subcommand.list_paths()
+        with ThreadPoolExecutor(max_workers=len(paths)) as executor:
+            results = executor.map(subcommand.documentation, paths)
+            commands_message = options\
+                .make_command_summary_string(sorted(results))
+
+        emitter.publish(
+            "Command line utility for the Mesosphere Datacenter Operating\n"
+            "System (DCOS). The Mesosphere DCOS is a distributed operating\n"
+            "system built around Apache Mesos. This utility provides tools\n"
+            "for easy management of a DCOS installation.\n")
+        emitter.publish("Available DCOS commands:")
+        emitter.publish(commands_message)
+        emitter.publish(
+            "\nGet detailed command description with 'dcos <command> --help'.")
+
         return 0
 
-    directory = util.dcos_path()
-    logger.debug("DCOS Path: {!r}".format(directory))
 
-    paths = subcommand.list_paths()
+def _help_command(command):
-    with ThreadPoolExecutor(max_workers=len(paths)) as executor:
+    """
-        results = executor.map(subcommand.documentation, paths)
+    :param command: the command name for which you want to see a help
-        commands_message = options.make_command_summary_string(sorted(results))
+    :type command: str
-
+    :returns: process return code
-    emitter.publish(
+    :rtype: int
-        "Command line utility for the Mesosphere Datacenter Operating\n"
+    """
-        "System (DCOS). The Mesosphere DCOS is a distributed operating\n"
-        "system built around Apache Mesos. This utility provides tools\n"
-        "for easy management of a DCOS installation.\n")
-    emitter.publish("Available DCOS commands:")
-    emitter.publish(commands_message)
-    emitter.publish(
-        "\nGet detailed command description with 'dcos <command> --help'.")
 
+    returncode, stdout, stderr = exec_command(['dcos', command, '--help'])
+    if returncode == 1:
+        emitter.publish(stderr.decode("utf-8"))
+        return 1
+    emitter.publish(stdout.decode("utf-8"))
     return 0

cli/tests/data/help/config.txt

@@ -0,0 +1,22 @@
+Get and set DCOS CLI configuration properties
+
+Usage:
+    dcos config --info
+    dcos config append <name> <value>
+    dcos config prepend <name> <value>
+    dcos config set <name> <value>
+    dcos config show [<name>]
+    dcos config unset [--index=<index>] <name>
+    dcos config validate
+
+Options:
+    -h, --help       Show this screen
+    --info           Show a short description of this subcommand
+    --version        Show version
+    --index=<index>  Index into the list. The first element in the list has an
+                     index of zero
+
+Positional Arguments:
+    <name>           The name of the property
+    <value>          The value of the property
+

cli/tests/data/help/marathon.txt

@@ -0,0 +1,99 @@
+Deploy and manage applications on the DCOS
+
+Usage:
+    dcos marathon --config-schema
+    dcos marathon --info
+    dcos marathon about
+    dcos marathon app add [<app-resource>]
+    dcos marathon app list [--json]
+    dcos marathon app remove [--force] <app-id>
+    dcos marathon app restart [--force] <app-id>
+    dcos marathon app show [--app-version=<app-version>] <app-id>
+    dcos marathon app start [--force] <app-id> [<instances>]
+    dcos marathon app stop [--force] <app-id>
+    dcos marathon app update [--force] <app-id> [<properties>...]
+    dcos marathon app version list [--max-count=<max-count>] <app-id>
+    dcos marathon deployment list [--json <app-id>]
+    dcos marathon deployment rollback <deployment-id>
+    dcos marathon deployment stop <deployment-id>
+    dcos marathon deployment watch [--max-count=<max-count>]
+         [--interval=<interval>] <deployment-id>
+    dcos marathon task list [--json <app-id>]
+    dcos marathon task show <task-id>
+    dcos marathon group add [<group-resource>]
+    dcos marathon group list [--json]
+    dcos marathon group show [--group-version=<group-version>] <group-id>
+    dcos marathon group remove [--force] <group-id>
+    dcos marathon group update [--force] <group-id> [<properties>...]
+
+Options:
+    -h, --help                       Show this screen
+
+    --info                           Show a short description of this
+                                     subcommand
+
+     --json                          Print json-formatted tasks
+
+    --version                        Show version
+
+    --force                          This flag disable checks in Marathon
+                                     during update operations
+
+    --app-version=<app-version>      This flag specifies the application
+                                     version to use for the command. The
+                                     application version (<app-version>) can be
+                                     specified as an absolute value or as
+                                     relative value. Absolute version values
+                                     must be in ISO8601 date format. Relative
+                                     values must be specified as a negative
+                                     integer and they represent the version
+                                     from the currently deployed application
+                                     definition
+
+    --group-version=<group-version>  This flag specifies the group version to
+                                     use for the command. The group version
+                                     (<group-version>) can be specified as an
+                                     absolute value or as relative value.
+                                     Absolute version values must be in ISO8601
+                                     date format. Relative values must be
+                                     specified as a negative integer and they
+                                     represent the version from the currently
+                                     deployed group definition
+
+    --config-schema                  Show the configuration schema for the
+                                     Marathon subcommand
+
+    --max-count=<max-count>          Maximum number of entries to try to fetch
+                                     and return
+
+    --interval=<interval>            Number of seconds to wait between actions
+
+Positional Arguments:
+    <app-id>                    The application id
+
+    <app-resource>              Path to a file or HTTP(S) URL containing
+                                the app's JSON definition. If omitted,
+                                the definition is read from stdin. For a
+                                detailed description see
+                                (https://mesosphere.github.io/
+                                marathon/docs/rest-api.html#post-/v2/apps).
+
+    <deployment-id>             The deployment id
+
+    <group-id>                  The group id
+
+    <group-resource>            Path to a file or HTTP(S) URL containing
+                                the group's JSON definition. If omitted,
+                                the definition is read from stdin. For a
+                                detailed description see
+                                (https://mesosphere.github.io/
+                                marathon/docs/rest-api.html#post-/v2/groups).
+
+    <instances>                 The number of instances to start
+
+    <properties>                Must be of the format <key>=<value>. E.g.
+                                cpus=2.0. If omitted, properties are read from
+                                stdin.
+
+    <task-id>                   The task id
+

cli/tests/data/help/node.txt

@@ -0,0 +1,24 @@
+Manage DCOS nodes
+
+Usage:
+    dcos node --info
+    dcos node [--json]
+    dcos node log [--follow --lines=N --master --slave=<slave-id>]
+    dcos node ssh [--option SSHOPT=VAL ...]
+                  [--config-file=<path>]
+                  [--user=<user>]
+                  (--master | --slave=<slave-id>)
+
+Options:
+    -h, --help              Show this screen
+    --info                  Show a short description of this subcommand
+    --json                  Print json-formatted nodes
+    --follow                Print data as the file grows
+    --lines=N               Print the last N lines [default: 10]
+    --master                Access the leading master
+    --slave=<slave-id>      Access the slave with the provided ID
+    --option SSHOPT=VAL     SSH option (see `man ssh_config`)
+    --config-file=<path>    Path to SSH config file
+    --user=<user>           SSH user [default: core]
+    --version               Show version
+

cli/tests/data/help/package.txt

@@ -0,0 +1,76 @@
+Install and manage DCOS packages
+
+Usage:
+    dcos package --config-schema
+    dcos package --info
+    dcos package describe [--app --cli --config]
+                          [--render]
+                          [--package-versions]
+                          [--options=<file>]
+                          [--package-version=<package_version>]
+                          <package_name>
+    dcos package install [--cli | [--app --app-id=<app_id>]]
+                         [--package-version=<package_version>]
+                         [--options=<file>] [--yes] <package_name>
+    dcos package list [--json --endpoints --app-id=<app-id> <package_name>]
+    dcos package search [--json <query>]
+    dcos package sources
+    dcos package uninstall [--cli | [--app --app-id=<app-id> --all]]
+                 <package_name>
+    dcos package update [--validate]
+
+Options:
+    --all                                  Apply the operation to all matching packages
+
+    --app                                  Apply the operation only to the package's
+                                           Marathon application
+
+    --app-id=<app-id>                      The application id
+
+    --cli                                  Apply the operation only to the package's CLI
+                                           command
+
+    --config                               Print the package's config.json, which contains
+                                           the configurable properties for marathon.json
+                                           and command.json
+
+    -h, --help                             Show this screen
+
+    --info                                 Show a short description of this subcommand
+
+    --options=<file>                       Path to a JSON file containing package
+                                           installation options
+
+    --package-version=<package_version>    Package version to install
+
+    --package-versions                     Print all versions for this package
+
+    --render                               Render the package's marathon.json or
+                                           command.json template with the values from
+                                           config.json and --options.  If not provided,
+                                           print the raw templates.
+
+    --validate                             Validate package content when updating sources
+
+    --version                              Show version
+
+    --yes                                  Assume "yes" is the answer to all prompts and
+                                           run non-interactively
+
+Configuration:
+    [package]
+    # Path to the local package cache.
+    cache_dir = "/var/dcos/cache"
+
+    # List of package sources, in search order.
+    #
+    # Three protocols are supported:
+    #   - Local file
+    #   - HTTPS
+    #   - Git
+    sources = [
+      "file:///Users/me/test-registry",
+      "https://my.org/registry",
+      "git://github.com/mesosphere/universe.git"
+    ]
+

cli/tests/data/help/service.txt

@@ -0,0 +1,37 @@
+Manage DCOS services
+
+Usage:
+    dcos service --info
+    dcos service [--inactive --json]
+    dcos service log [--follow --lines=N --ssh-config-file=<path>]
+                     <service> [<file>]
+    dcos service shutdown <service-id>
+
+Options:
+    -h, --help                  Show this screen
+
+    --info                      Show a short description of this subcommand
+
+    --ssh-config-file=<path>    Path to SSH config file.  Used to access
+                                marathon logs.
+
+    --follow                    Print data as the file grows
+
+    --inactive                  Show inactive services in addition to active
+                                ones. Inactive services are those that have
+                                been disconnected from master, but haven't yet
+                                reached their failover timeout.
+
+    --json                      Print json-formatted services
+
+    --lines=N                   Print the last N lines [default: 10]
+
+    --version                   Show version
+
+Positional Arguments:
+    <file>                      Output this file. [default: stdout]
+
+    <service>                   The DCOS Service name.
+
+    <service-id>                The DCOS Service ID
+

cli/tests/data/help/task.txt

@@ -0,0 +1,24 @@
+Manage DCOS tasks
+
+Usage:
+    dcos task --info
+    dcos task [--completed --json <task>]
+    dcos task log [--completed --follow --lines=N] <task> [<file>]
+    dcos task ls [--long] <task> [<path>]
+
+Options:
+    -h, --help    Show this screen
+    --info        Show a short description of this subcommand
+    --completed   Include completed tasks as well
+    --follow      Print data as the file grows
+    --json        Print json-formatted tasks
+    --lines=N     Print the last N lines [default: 10]
+    --long        Use a long listing format
+    --version     Show version
+
+Positional Arguments:
+    <file>        Print this file. [default: stdout]
+    <path>        List this directory. [default: '.']
+    <task>        Only match tasks whose ID matches <task>.  <task> may be
+                  a substring of the ID, or a unix glob pattern.
+

cli/tests/integrations/test_help.py

@@ -5,8 +5,9 @@ def test_help():
     stdout = b"""Display command line usage information
 
 Usage:
-    dcos help --info
     dcos help
+    dcos help --info
+    dcos help <command>
 
 Options:
     --help     Show this screen
@@ -49,3 +50,39 @@ Get detailed command description with 'dcos <command> --help'.
 
     assert_command(['dcos', 'help'],
                    stdout=stdout)
+
+
+def test_help_config():
+    with open('tests/data/help/config.txt') as content:
+        assert_command(['dcos', 'help', 'config'],
+                       stdout=content.read().encode('utf-8'))
+
+
+def test_help_marathon():
+    with open('tests/data/help/marathon.txt') as content:
+        assert_command(['dcos', 'help', 'marathon'],
+                       stdout=content.read().encode('utf-8'))
+
+
+def test_help_node():
+    with open('tests/data/help/node.txt') as content:
+        assert_command(['dcos', 'help', 'node'],
+                       stdout=content.read().encode('utf-8'))
+
+
+def test_help_package():
+    with open('tests/data/help/package.txt') as content:
+        assert_command(['dcos', 'help', 'package'],
+                       stdout=content.read().encode('utf-8'))
+
+
+def test_help_service():
+    with open('tests/data/help/service.txt') as content:
+        assert_command(['dcos', 'help', 'service'],
+                       stdout=content.read().encode('utf-8'))
+
+
+def test_help_task():
+    with open('tests/data/help/task.txt') as content:
+        assert_command(['dcos', 'help', 'task'],
+                       stdout=content.read().encode('utf-8'))