From 0c8fdfafa8a85dd6e25497a9f9af9694e75ee4a1 Mon Sep 17 00:00:00 2001 From: Yujun Zhang Date: Thu, 30 Mar 2017 10:14:04 +0800 Subject: Normalize all section headers - folder with `index.rst` for parts, using # with overline for heading - `*.rst` file for chapter, using * with overline for heading In each *.rst file, use the following token for heading - =, for sections - -, for subsections - ^, for subsubsections - ", for paragraphs Change-Id: I6c247c1f1e27e891d0dade099195ef521f7dbb72 Signed-off-by: Yujun Zhang --- docs/testing/developer/devguide/api.rst | 11 +-- docs/testing/developer/devguide/arch.rst | 6 +- docs/testing/developer/devguide/cli.rst | 103 ++++++++++++++++++++++----- docs/testing/developer/devguide/index.rst | 6 +- docs/testing/developer/devguide/overview.rst | 31 ++++---- 5 files changed, 113 insertions(+), 44 deletions(-) (limited to 'docs/testing/developer/devguide') diff --git a/docs/testing/developer/devguide/api.rst b/docs/testing/developer/devguide/api.rst index 48ae3ae4..491c70f8 100644 --- a/docs/testing/developer/devguide/api.rst +++ b/docs/testing/developer/devguide/api.rst @@ -1,9 +1,10 @@ -********************************************** -QTIP RESTful Application Programming Interface -********************************************** +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 -Abstract -######## + +*************************************** +API - Application Programming Interface +*************************************** 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. diff --git a/docs/testing/developer/devguide/arch.rst b/docs/testing/developer/devguide/arch.rst index d95faba6..6b9208e9 100644 --- a/docs/testing/developer/devguide/arch.rst +++ b/docs/testing/developer/devguide/arch.rst @@ -3,9 +3,9 @@ .. (c) 2017 ZTE Corp. -######################## -QTIP Architecture Design -######################## +************ +Architecture +************ In Danube, QTIP releases its standalone mode, which is also know as ``solo``: diff --git a/docs/testing/developer/devguide/cli.rst b/docs/testing/developer/devguide/cli.rst index 487bdec5..7c681a64 100644 --- a/docs/testing/developer/devguide/cli.rst +++ b/docs/testing/developer/devguide/cli.rst @@ -1,24 +1,93 @@ -- Which framework has been used and why -- How to extend to more commands +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 -Original content from DEVELOP.md - ### CLI +**************************** +CLI - Command Line Interface +**************************** - Click currently supports Bash completion. The prerequisite for this is that the program - needs to be installed correctly. To install Qtip, execute the following command in root - folder of Qtip: +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. - ``` - cd - pip install -e . - ``` +Framework +========= - Once the installation has been completed successfully, the following needs to be added to - the `.bashrc` file: +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. - ``` - eval "$(_QTIP_COMPLETE=source qtip)" - ``` +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. - The above would activate command completion for Qtip. +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/developer/devguide/index.rst b/docs/testing/developer/devguide/index.rst index 89113e56..1c993dc9 100644 --- a/docs/testing/developer/devguide/index.rst +++ b/docs/testing/developer/devguide/index.rst @@ -3,9 +3,9 @@ .. (c) 2016 ZTE Corp. -########################## -QTIP Design Specifications -########################## +*************** +Developer Guide +*************** .. toctree:: :maxdepth: 2 diff --git a/docs/testing/developer/devguide/overview.rst b/docs/testing/developer/devguide/overview.rst index d394574e..1d7e22fe 100644 --- a/docs/testing/developer/devguide/overview.rst +++ b/docs/testing/developer/devguide/overview.rst @@ -3,9 +3,9 @@ .. (c) 2017 ZTE Corporation -######## +******** Overview -######## +******** QTIP uses Python as primary programming language and build the framework from the following packages @@ -19,16 +19,15 @@ docs `sphinx`_ - a tool that makes it easy to create intelligent and beautif testing `pytest`_ - a mature full-featured Python testing tool that helps you write better programs ======== =============================================================================================================== -*********** + Source Code -*********** +=========== - The structure of repository is based on the recommended sample in -`The Hitchhiker's Guide to Python`_ +The structure of repository is based on the recommended sample in `The Hitchhiker's Guide to Python`_ -================== ======================================================================================================== +================== ==================================================================================================== Path Content -================== ======================================================================================================== +================== ==================================================================================================== ``./benchmarks/`` builtin benchmark assets including plan, QPI and metrics ``./contrib/`` independent project/plugin/code contributed to QTIP ``./docker/`` configuration for building Docker image for QTIP deployment @@ -38,11 +37,11 @@ Path Content ``./qtip/`` the actual package ``./tests/`` package functional and unit tests ``./third-party/`` third part included in QTIP project -================== ======================================================================================================== +================== ==================================================================================================== + -************ Coding Style -************ +============ QTIP follows `OpenStack Style Guidelines`_ for source code and commit message. @@ -52,19 +51,19 @@ Specially, it is recommended to link each patch set with a JIRA issue. Put:: in commit message to create an automatic link. -******* + Testing -******* +======= All testing related code are stored in ``./tests/`` -================== ======================================================================================================== +================== ==================================================================================================== Path Content -================== ======================================================================================================== +================== ==================================================================================================== ``./tests/data/`` data fixtures for testing ``./tests/unit/`` unit test for each module, follow the same layout as ./qtip/ ``./conftest.py`` pytest configuration in project scope -================== ======================================================================================================== +================== ==================================================================================================== `tox`_ is used to automate the testing tasks -- cgit 1.2.3-korg