Merge "Restructure Rally docs"

doc/feature_request/README.rst

@@ -2,10 +2,8 @@
 Feature requests
 ================
 
-To request a new feature you should create a document similar to other feature
-requests. And contribute it to this directory using next instruction_.
+To request a new feature, you should create a document similar to other feature requests. And contribute it to this directory using the next instruction_.
 
-If you don't have time to contribute via gerrit,
-please contact Boris Pavlovic (boris@pavlovic.me)
+If you don't have time to contribute your feature request via gerrit, please contact Boris Pavlovic (boris@pavlovic.me)
 
-.. _instruction:  https://wiki.openstack.org/wiki/Rally/Develop#How_to_contribute
+.. _instruction:  http://rally.readthedocs.org/en/latest/contribute.html#how-to-contribute

doc/source/concepts.rst

@@ -75,8 +75,8 @@ Note that inside each scenario configuration, the benchmark scenario is actually
 
 
 .. _ScenariosDevelopment:
-Developer's  view
-^^^^^^^^^^^^^^^^^
+Developer's view
+^^^^^^^^^^^^^^^^
 
 From the developer's perspective, a benchmark scenario is a method marked by a **@scenario** decorator and placed in a class that inherits from the base `Scenario <https://github.com/stackforge/rally/blob/master/rally/benchmark/scenarios/base.py#L40>`_ class and located in some subpackage of `rally.benchmark.scenarios <https://github.com/stackforge/rally/tree/master/rally/benchmark/scenarios>`_. There may be arbitrary many benchmark scenarios in a scenario class; each of them should be referenced to (in the task configuration file) as *ScenarioClassName.method_name*.
 
@@ -162,8 +162,8 @@ Also, all scenario runners can be provided (again, through the **"runner"** sect
 
 
 .. _RunnersDevelopment:
-Developer's  view
-^^^^^^^^^^^^^^^^^
+Developer's view
+^^^^^^^^^^^^^^^^
 
 It is possible to extend Rally with new Scenario Runner types, if needed. Basically, each scenario runner should be implemented as a subclass of the base `ScenarioRunner <https://github.com/stackforge/rally/blob/master/rally/benchmark/runners/base.py#L137>`_ class and located in the `rally.benchmark.runners package <https://github.com/stackforge/rally/tree/master/rally/benchmark/runners>`_. The interface each scenario runner class should support is fairly easy:
 
@@ -318,27 +318,3 @@ The *hidden* attribute defines whether the context should be a *hidden* one. **H
 it configuration via task and break his cloud.
 
 If you want to dive deeper, also see the context manager (:mod:`rally.benchmark.context.base`) class that actually implements the algorithm described above.
-
-
-Plugins
--------
-
-Rally provides an opportunity to create and use a custom benchmark scenario, runner or context as a plugin. The plugins mechanism can be used to simplify some experiments with new scenarios and to facilitate their creation by users who don't want to edit the actual Rally code.
-
-Placement
-^^^^^^^^^
-
-Put the plugin into the **/opt/rally/plugins** or **~/.rally/plugins** directory  or it's subdirectories and it will be autoloaded. The corresponding module should have ".py" extension. Directories are not created automatically, you should create them by hand or you can use script **unpack_plugins_samles.sh** from **doc/samples/plugins** which will internally create directory **~/.rally/plugins** (see more about this script into **Samples** section).
-
-Creation
-^^^^^^^^
-
-Inherit a class for your plugin from base class for scenario, runner or context depends on what type of plugin you want create.
-
-See more information about `scenarios <ScenariosDevelopment>`_, `runnres <RunnersDevelopment>`_ and `contexts <ContextDevelopment>`_ creation.
-
-
-Usage
-^^^^^
-
-Specify your plugin's information into a task configuration file. See `how to work with task configuration file <https://github.com/stackforge/rally/blob/master/doc/samples/tasks/README.rst>`_. You can find samples of configuration files for different types of plugins in corresponded folders `here <https://github.com/stackforge/rally/tree/master/doc/samples/plugins>`_.

doc/source/improve_rally.rst → doc/source/contribute.rst

@@ -1,5 +1,5 @@
 ..
-      Copyright 2014 Mirantis Inc. All Rights Reserved.
+      Copyright 2015 Mirantis Inc. All Rights Reserved.
 
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain
@@ -15,31 +15,19 @@
 
 
 
-.. _improve_rally:
-
-Improve Rally
-=============
-
-Main directions of work
------------------------
-
-    * **Benchmarks**. Improvements in the benchmarking engine & developing new benchmark scenarios.
-    * **Deployments**. Making Rally able to support multiple cloud deployment facilities, e.g. Fuel.
-    * **CLI**. Enriching the command line interface for Rally.
-    * **API**. Work around making Rally to be a Benchmark-as-a-Service system & developing rally-pythonclient.
-    * **Incubation**. Efforts to make Rally an integrated project in OpenStack.
-    * **Share system**. Benchmark results visualization and paste.openstack.org-like sharing system.
-    * **Tempest**. Integration of Tempest tests in Rally for deployment verification.
+.. _contribute:
 
+Contribute to Rally
+===================
 
 Where to begin
 --------------
 
-It is extremetly simple to participate in different Rally development lines mentioned above. The **Good for start** section of our `Trello board <https://trello.com/b/DoD8aeZy/rally>`_ contains a wide range of tasks perfectly suited for you to quickly and smoothly start contributing to Rally. As soon as you have chosen a task, just log in to Trello, join the corresponding card and move it to the **In progress** section.
+Please take a look `our Roadmap <https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0>`_ to get information about our current work directions.
 
-The most Trello cards contain basic descriptions of what is to be done there; in case you have questions or want to share your ideas, be sure to contanct us at the ``#openstack-rally`` IRC channel on **irc.freenode.net**.
+In case you have questions or want to share your ideas, be sure to contact us at the ``#openstack-rally`` IRC channel on **irc.freenode.net**.
 
-If you want to grasp a better understanding of several main design concepts used throughout the Rally code (such as **benchmark scenarios**, **contexts** etc.), please read this :ref:`article <main_concepts>`.
+If you are going to contribute to Rally, you will probably need to grasp a better understanding of several main design concepts used throughout our project (such as **benchmark scenarios**, **contexts** etc.). To do so, please read :ref:`this article <main_concepts>`.
 
 
 How to contribute
@@ -78,15 +66,15 @@ Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starti
 
 7. Start coding
 
-8. Run the test suite locally to make sure nothing broke, e.g.:
+8. Run the test suite locally to make sure nothing broke, e.g. (this will run py26/py27/pep8 tests):
 
 .. code-block:: none
 
     tox
 
-**(NOTE you should have installed tox<=1.6.1 )**
+**(NOTE: you should have installed tox<=1.6.1 )**
 
-If you extend Rally with new functionality, make sure you also have provided unit tests for it.
+If you extend Rally with new functionality, make sure you have also provided unit and/or functional tests for it.
 
 9. Commit your work using:
 
@@ -111,3 +99,80 @@ That is the awesome tool we installed earlier that does a lot of hard work for y
 
 
 (This tutorial is based on: http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)
+
+Testing
+-------
+
+Please, don't hesitate to write tests ;)
+
+
+Unit tests
+^^^^^^^^^^
+
+*Files: /tests/unit/**
+
+The goal of unit tests is to ensure that internal parts of the code work properly.
+All internal methods should be fully covered by unit tests with a reasonable mocks usage.
+
+
+About Rally unit tests:
+
+- All `unit tests <http://en.wikipedia.org/wiki/Unit_testing>`_ are located inside /tests/unit/*
+- Tests are written on top of: *testtools*, *fixtures* and *mock* libs
+- `Tox <https://tox.readthedocs.org/en/latest/>`_ is used to run unit tests
+
+
+To run unit tests locally::
+
+  $ pip install tox
+  $ tox
+
+To run py26, py27 or pep8 only::
+
+  $ tox -e <name>
+
+  #NOTE: <name> is one of py26, py27 or pep8
+
+To get test coverage::
+
+  $ tox -e cover
+
+  #NOTE: Results will be in /cover/index.html
+
+To generate docs::
+
+  $ tox -e docs
+
+  #NOTE: Documentation will be in doc/source/_build/html/index.html
+
+Functional tests
+^^^^^^^^^^^^^^^^
+
+*Files: /tests/functional/**
+
+The goal of `functional tests <https://en.wikipedia.org/wiki/Functional_testing>`_ is to check that everything works well together.
+Fuctional tests use Rally API only and check responses without touching internal parts.
+
+To run functional tests locally::
+
+  $ source openrc
+  $ rally deployment create --fromenv --name testing
+  $ tox -e cli
+
+  #NOTE: openrc file with OpenStack admin credentials
+
+Rally CI scripts
+^^^^^^^^^^^^^^^^
+
+*Files: /tests/ci/**
+
+This directory contains scripts and files related to the Rally CI system.
+
+Rally Style Commandments
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Files: /tests/hacking/*
+
+This module contains Rally specific hacking rules for checking commandments.
+
+For more information about Style Commandments, read the `OpenStack Style Commandments manual <http://docs.openstack.org/developer/hacking/>`_.

doc/source/feature_requests.rst

@@ -1,6 +1,31 @@
-.. include:: feature_request/README.rst
+..
+      Copyright 2015 Mirantis Inc. All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _feature_requests:
+
+Request New Features
+====================
+
+To request a new feature, you should create a document similar to other feature requests and then contribute it to the **doc/feature_request** directory of the Rally repository (see the :ref:`How-to-contribute tutorial <contribute>`).
+
+If you don't have time to contribute your feature request via gerrit, please contact Boris Pavlovic (boris@pavlovic.me)
+
+Active feature requests:
 
 .. toctree::
    :glob:
+   :maxdepth: 1
 
    feature_request/*