From e5d4ac457f815e70afbd55ebbf1924084ec5ec8c Mon Sep 17 00:00:00 2001 From: Taseer Date: Wed, 22 Mar 2017 14:33:12 +0500 Subject: Update CLI docs. JIRA: QTIP-231 Change-Id: I44bc75239e9ff59a70ec9070092101f021a3a291 Signed-off-by: Taseer Ahmed --- docs/testing/developer/design/cli.rst | 92 +++++++++++++++++++++++++++++++++++ docs/testing/user/userguide/cli.rst | 38 +++++++++++++++ 2 files changed, 130 insertions(+) create mode 100644 docs/testing/developer/design/cli.rst create mode 100644 docs/testing/user/userguide/cli.rst diff --git a/docs/testing/developer/design/cli.rst b/docs/testing/developer/design/cli.rst new file mode 100644 index 00000000..72d1fbaf --- /dev/null +++ b/docs/testing/developer/design/cli.rst @@ -0,0 +1,92 @@ +*************************** +QTIP Command Line Interface +*************************** + +Abstract +######## + +QTIP consists of different tools(metrics) to benchmark the NFVI. These metrics fall under different NFVI +subsystems(QPI's) such as compute, storage and network. A plan consists of one or more QPI's, depending upon how +the end user would want to measure performance. CLI is designed to help the user, execute benchmarks and +view respective scores. + +Framework +========= + +QTIP CLI has been created using the Python package `Click`_, Command Line Interface Creation Kit. It has been +chosen for number of reasons. It presents the user with a very simple yet powerful API to build complex +applications. One of the most striking features is command nesting. + +As explained, QTIP consists of metrics, QPI's and plans. CLI is designed to provide interface to all +these components. It is responsible for execution, as well as provide listing and details of each individual +element making up these components. + +Design +====== + +CLI's entry point extends Click's built in MultiCommand class object. It provides two methods, which are +overridden to provide custom configurations. + +.. code-block:: python + + class QtipCli(click.MultiCommand): + + def list_commands(self, ctx): + rv = [] + for filename in os.listdir(cmd_folder): + if filename.endswith('.py') and \ + filename.startswith('cmd_'): + rv.append(filename[4:-3]) + rv.sort() + return rv + + def get_command(self, ctx, name): + try: + if sys.version_info[0] == 2: + name = name.encode('ascii', 'replace') + mod = __import__('qtip.cli.commands.cmd_' + name, + None, None, ['cli']) + except ImportError: + return + return mod.cli + +Commands and subcommands will then be loaded by the ``get_command`` method above. + +Extending the Framework +======================= + +Framework can be easily extended, as per the users requirements. One such example can be to override the builtin +configurations with user defined ones. These can be written in a file, loaded via a Click Context and passed +through to all the commands. + +.. code-block:: python + + class Context: + + def __init__(): + + self.config = ConfigParser.ConfigParser() + self.config.read('path/to/configuration_file') + + def get_paths(): + + paths = self.config.get('section', 'path') + return paths + +The above example loads configuration from user defined paths, which then need to be provided to the actual +command definitions. + +.. code-block:: python + + from qtip.cli.entry import Context + + pass_context = click.make_pass_decorator(Context, ensure=False) + + @cli.command('list', help='List the Plans') + @pass_context + def list(ctx): + plans = Plan.list_all(ctx.paths()) + table = utils.table('Plans', plans) + click.echo(table) + +.. _Click: http://click.pocoo.org/5/ diff --git a/docs/testing/user/userguide/cli.rst b/docs/testing/user/userguide/cli.rst new file mode 100644 index 00000000..e18a36f9 --- /dev/null +++ b/docs/testing/user/userguide/cli.rst @@ -0,0 +1,38 @@ +************** +QTIP CLI Usage +************** + +QTIP consists of a number of benchmarking tools or metrics, grouped under QPI's. QPI's map to the different +components of a NFVI ecosystem, such as compute, network and storage. Depending on the type of application, +a user may group them under plans. + +QTIP CLI provides interface to all of the above the components. A help page provides a list of all the commands +along with a short description. +:: + + qtip [-h|--help] + +Typically a complete plan is executed at the +target environment. QTIP defaults to a number of sample plans. One may be able to list them using +:: + + qtip plan list + +One can also be able to view the details about a specific plan. +:: + + qtip plan show + +where *plan_name* is one of those listed from the previous command. + +To execute a complete plan +:: + + qtip plan run + +Similarly, the same commands can be used for the other two components making up the plans, i.e QPI's and metrics. + +Debug option helps identify the error by providing a detailed traceback. It can be enabled as +:: + + qtip [-d|--debug] plan run -- cgit 1.2.3-korg