[docs][6] Re-design docs to cover all user-groups

All information related to Rally community and project
info has been refactored. Modified files fit 80 symbols
margin where possible.

[TODO] add 80 symbols margin check similar to what
       Performance Documentation has

Change-Id: Id4f33733c2b9aa141df4eeb0f24a21d82290a962

CONTRIBUTING.rst

@@ -0,0 +1 @@
+doc/source/contribute.rst

doc/feature_request/README.rst

@@ -2,8 +2,10 @@
 Feature requests
 ================
 
-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_.
+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 your feature request via gerrit, please contact Boris Pavlovic (boris@pavlovic.me)
+If you don't have time to contribute your feature request via Gerrit, please
+contact Andrey Kurilin (andr.kurilin@gmail.com)
 
 .. _instruction: http://rally.readthedocs.org/en/latest/contribute.html#how-to-contribute

doc/feature_request/check_queue_perfdata.rst

@@ -1,19 +1,22 @@
-===========================
+====================
 Check queue perfdata
-===========================
+====================
-
 
 Use case
-————
+--------
-Sometimes OpenStack services use common messaging system very prodigally. For example neutron metering agent sending all database table data on new object creation i.e https://review.openstack.org/#/c/143672/. It cause to neutron degradation and other obvious problems.
+Sometimes OpenStack services use common messaging system very prodigally. For
-It will be nice to have a way to track messages count and messages size in queue during tests/benchmarks.
+example Neutron metering agent sending all database table data on new object
-
+creation i.e https://review.openstack.org/#/c/143672/. It cause to Neutron
+degradation and other obvious problems. It will be nice to have a way to track
+messages count and messages size in queue during tests/benchmarks.
 
 Problem description
-—————————
+-------------------
+
 Heavy usage of queue isn’t checked.
 
-
 Possible solution
-————————
+-----------------
-* Before running tests/benchmarks start process which will connect to queue topics and measure messages count, size and other data which we need.
+
+* Before running tests/benchmarks start process which will connect to queue
+topics and measure messages count, size and other data which we need.

doc/feature_request/distributed_load_generation.rst

@@ -11,7 +11,6 @@ like 10-100k request per second for benchmarking.
 To generate such huge load Rally have to create load from different
 servers.
 
-
 Problem Description
 -------------------
 

doc/feature_request/installing_isolated.rst

@@ -1,15 +1,15 @@
-=============================================================================
+=================================================================================
 Installation script: ``--pypi-mirror``, ``--package-mirror`` and ``--venv-mirror``
-=============================================================================
+=================================================================================
 
 
 Use case
 --------
 
 Installation is pretty easy when there is an Internet connection available.
-And there is surely a number of OpenStack uses when whole environment is isolated.
+And there is surely a number of OpenStack uses when whole environment is
-In this case, we need somehow specify where installation script should take 
+isolated. In this case, we need somehow specify where installation script
-required libs and packages.
+should take required libs and packages.
 
 
 Problem description

doc/feature_request/launch_specific_benchmark.rst

@@ -8,7 +8,7 @@ Use case
 
 A developer is working on a feature that is covered by one or more specific
 benchmarks/scenarios.  He/she would like to execute a rally task with an
-existing task template file (yaml or json) indicating exactly which
+existing task template file (YAML or JSON) indicating exactly which
 benchmark(s) will be executed.
 
 

doc/feature_request/multiple_attach_volume.rst

@@ -1,17 +1,18 @@
-====================
+======================
 Multiple attach volume
-====================
+======================
 
 
 Use Case
 --------
-Since multiple volume attaching support to OpenStack Mitaka, one volume can be attached to several
+Since multiple volume attaching support to OpenStack Mitaka, one volume can be
-instances or hosts, rally should add scenarios about multiple attach volume.
+attached to several instances or hosts, Rally should add scenarios about
+multiple attach volume.
 
 
 Problem Description
 -------------------
-Rally lack of scenarios about multiple attach volume
+Rally lack of scenarios about multiple attach volume.
 
 
 Possible solution

doc/feature_request/production_ready_cleanup.rst

@@ -32,6 +32,5 @@ Problem Description
 * Disaster recovery
 
   Rally should use special name patterns, to be able to delete resources
-  in such case if something went wrong with server that is running rally. And
+  in such case if something went wrong with server that is running Rally. And
-  you have just new instance (without old rally db) of rally on new server.
+  you have just new instance (without old Rally DB) of Rally on new server.
-

doc/source/contribute.rst

@@ -21,19 +21,27 @@ Contribute to Rally
 Where to begin
 --------------
 
-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.
+Please take a look `our Roadmap`_ to get information about our current work
+directions.
 
-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**.
+In case you have questions or want to share your ideas, be sure to contact us
+either at `Rally-dev/Lobby`_ channel on **Gitter** messenger (or, less
+preferably, at the ``#openstack-rally`` IRC channel on **irc.freenode.net**).
 
-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>`.
+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
 -----------------
 
-1. You need a `Launchpad <https://launchpad.net/>`_ account and need to be joined to the `OpenStack team <https://launchpad.net/openstack>`_. You can also join the `Rally team <https://launchpad.net/rally>`_ if you want to. Make sure Launchpad has your SSH key, Gerrit (the code review system) uses this.
+1. You need a `Launchpad`_ account and need to be joined to the
+`OpenStack team`_. You can also join the `Rally team`_ if you want to. Make
+sure Launchpad has your SSH key, Gerrit (the code review system) uses this.
 
-2. Sign the CLA as outlined in the `account setup <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_ section of the developer guide.
+2. Sign the CLA as outlined in the `account setup`_ section of the developer guide.
 
 3. Tell git your details:
 
@@ -42,13 +50,17 @@ How to contribute
     git config --global user.name "Firstname Lastname"
     git config --global user.email "your_email@youremail.com"
 
-4. Install git-review. This tool takes a lot of the pain out of remembering commands to push code up to Gerrit for review and to pull it back down to edit it. It is installed using:
+4. Install git-review. This tool takes a lot of the pain out of remembering
+commands to push code up to Gerrit for review and to pull it back down to edit
+it. It is installed using:
 
 .. code-block:: bash
 
     pip install git-review
 
-Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starting to include git-review in their repositories so it can also be installed using the standard package manager.
+Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also
+starting to include git-review in their repositories so it can also be
+installed using the standard package manager.
 
 5. Grab the Rally repository:
 
@@ -64,7 +76,8 @@ 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. (this will run py34/py27/pep8 tests):
+8. Run the test suite locally to make sure nothing broke, e.g. (this will run
+py34/py27/pep8 tests):
 
 .. code-block:: bash
 
@@ -72,7 +85,8 @@ Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starti
 
 **(NOTE: you should have installed tox<=1.6.1)**
 
-If you extend Rally with new functionality, make sure you have also provided unit and/or functional 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:
 
@@ -81,7 +95,8 @@ If you extend Rally with new functionality, make sure you have also provided uni
     git commit -a
 
 
-Make sure you have supplied your commit with a neat commit message, containing a link to the corresponding blueprint / bug, if appropriate.
+Make sure you have supplied your commit with a neat commit message, containing
+a link to the corresponding blueprint / bug, if appropriate.
 
 10. Push the commit up for code review using:
 
@@ -89,14 +104,19 @@ Make sure you have supplied your commit with a neat commit message, containing a
 
     git review -R
 
-That is the awesome tool we installed earlier that does a lot of hard work for you.
+That is the awesome tool we installed earlier that does a lot of hard work for
+you.
 
-11. Watch your email or `review site <http://review.openstack.org/>`_, it will automatically send your code for a battery of tests on our `Jenkins setup <http://jenkins.openstack.org/>`_ and the core team for the project will review your code. If there are any changes that should be made they will let you know.
+11. Watch your email or `review site`_, it will automatically send your code
+for a battery of tests on our `Jenkins setup`_ and the core team for the
+project will review your code. If there are any changes that should be made
+they will let you know.
 
 12. When all is good the review site  will automatically merge your code.
 
 
-(This tutorial is based on: http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)
+(This tutorial is based on:
+http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)
 
 Testing
 -------
@@ -109,15 +129,16 @@ Unit tests
 
 *Files: /tests/unit/**
 
-The goal of unit tests is to ensure that internal parts of the code work properly.
+The goal of unit tests is to ensure that internal parts of the code work
-All internal methods should be fully covered by unit tests with a reasonable mocks usage.
+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/*
+- All `unit tests`_ are located inside /tests/unit/*
 - Tests are written on top of: *testtools* and *mock* libs
-- `Tox <https://tox.readthedocs.org/en/latest/>`_ is used to run unit tests
+- `Tox`_ is used to run unit tests
 
 
 To run unit tests locally:
@@ -184,8 +205,9 @@ 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.
+The goal of `functional tests`_ is to check that everything works well
-Functional tests use Rally API only and check responses without touching internal parts.
+together. Functional tests use Rally API only and check responses without
+touching internal parts.
 
 To run functional tests locally:
 
@@ -200,11 +222,10 @@ To run functional tests locally:
 Output of every Rally execution will be collected under some reports root in
 directory structure like: reports_root/ClassName/MethodName_suffix.extension
 This functionality implemented in tests.functional.utils.Rally.__call__ method.
-Use 'gen_report_path' method of 'Rally' class to get automatically generated file
+Use 'gen_report_path' method of 'Rally' class to get automatically generated
-path and name if you need. You can use it to publish html reports, generated
+file path and name if you need. You can use it to publish html reports,
-during tests.
+generated during tests. Reports root can be passed throw environment variable
-Reports root can be passed throw environment variable 'REPORTS_ROOT'. Default is
+'REPORTS_ROOT'. Default is 'rally-cli-output-files'.
-'rally-cli-output-files'.
 
 Rally CI scripts
 ^^^^^^^^^^^^^^^^
@@ -220,4 +241,20 @@ Rally Style Commandments
 
 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/>`_.
+For more information about Style Commandments, read the
+`OpenStack Style Commandments manual`_.
+
+.. references:
+
+.. _our Roadmap: https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0
+.. _Rally-dev/Lobby: https://gitter.im/rally-dev/Lobby
+.. _Launchpad: https://launchpad.net/
+.. _OpenStack team: https://launchpad.net/openstack
+.. _Rally team: https://launchpad.net/rally
+.. _account setup: http://docs.openstack.org/infra/manual/developers.html#development-workflow
+.. _review site: http://review.openstack.org/
+.. _Jenkins setup: http://jenkins.openstack.org/
+.. _unit tests: http://en.wikipedia.org/wiki/Unit_testing
+.. _Tox: https://tox.readthedocs.org/en/latest/
+.. _functional tests: https://en.wikipedia.org/wiki/Functional_testing
+.. _OpenStack Style Commandments manual:  http://docs.openstack.org/developer/hacking/

doc/source/index.rst

@@ -45,5 +45,4 @@ Contents
    plugins/index
    contribute
    feature_requests
-   project_info
+   project_info/index
-   release_notes

doc/source/project_info/index.rst

@@ -15,8 +15,8 @@
 
 .. _project_info:
 
-Project Info
+Project Info and Release Notes
-============
+==============================
 
 Maintainers
 -----------
@@ -123,20 +123,39 @@ Plugin Core reviewers
 
 Useful links
 ------------
-- `Source code <https://github.com/openstack/rally>`_
+- `Source code`_
-- `Rally road map <https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0>`_
+- `Rally roadmap`_
-- `Project space <http://launchpad.net/rally>`_
+- `Project space`_
-- `Bugs <https://bugs.launchpad.net/rally>`_
+- `Bugs`_
-- `Patches on review <https://review.openstack.org/#/q/status:open+rally,n,z>`_
+- `Patches on review`_
-- `Meeting logs <http://eavesdrop.openstack.org/meetings/rally/2016/>`_ (server: **irc.freenode.net**, channel: **#openstack-meeting**)
+- `Meeting logs`_ (server: **irc.freenode.net**, channel:
-- `IRC logs <http://irclog.perlgeek.de/openstack-rally>`_ (server: **irc.freenode.net**, channel: **#openstack-rally**)
+   **#openstack-meeting**)
-- `Gitter chat <https://gitter.im/rally-dev/Lobby>`_
+- `IRC logs`_ (server: **irc.freenode.net**, channel: **#openstack-rally**)
-- `Trello board <https://trello.com/b/DoD8aeZy/rally>`_
+- `Gitter chat`_
+- `Trello board`_
 
 
 Where can I discuss and propose changes?
 ----------------------------------------
 - Our IRC channel: **#openstack-rally** on **irc.freenode.net**;
-- Weekly Rally team meeting (in IRC): **#openstack-meeting** on **irc.freenode.net**, held on Mondays at 14:00 UTC;
+- Weekly Rally team meeting (in IRC): **#openstack-meeting** on
-- OpenStack mailing list: **openstack-dev@lists.openstack.org** (see `subscription and usage instructions <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`_);
+  **irc.freenode.net**, held on Mondays at 14:00 UTC;
-- `Rally team on Launchpad <https://launchpad.net/rally>`_: Answers/Bugs/Blueprints.
+- OpenStack mailing list: **openstack-dev@lists.openstack.org** (see
+  `subscription and usage instructions`_);
+- `Rally team on Launchpad`_: Answers/Bugs/Blueprints.
+
+.. include:: release_notes.rst
+
+.. references:
+
+.. _Source code: https://github.com/openstack/rally
+.. _Rally roadmap: https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0
+.. _Project space: http://launchpad.net/rally
+.. _Bugs: https://bugs.launchpad.net/rally
+.. _Patches on review: https://review.openstack.org/#/q/status:open+rally,n,z
+.. _Meeting logs: http://eavesdrop.openstack.org/meetings/rally/2016/
+.. _IRC logs: http://irclog.perlgeek.de/openstack-rally
+.. _Gitter chat: https://gitter.im/rally-dev/Lobby
+.. _Trello board: https://trello.com/b/DoD8aeZy/rally
+.. _subscription and usage instructions: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
+.. _Rally team on Launchpad: https://launchpad.net/rally

doc/source/project_info/release_notes

@@ -0,0 +1 @@
+../../release_notes/

doc/source/project_info/release_notes.rst

@@ -16,7 +16,7 @@
 .. _release_notes:
 
 Release Notes
-=============
+-------------
 
 .. toctree::
    :maxdepth: 1

doc/source/release_notes

@@ -1 +0,0 @@
-../release_notes