From 4292063876caa10ca3a308bbd315cbd27b33d325 Mon Sep 17 00:00:00 2001 From: Dina Belova Date: Wed, 16 Nov 2016 13:28:10 -0800 Subject: [PATCH] [docs][2] Re-design docs to cover all user-groups First pack of changes in upcoming chain to redesign Rally docs. All information related to the installation and upgrades process separated and refactored. Modified files fit 80 symbols margin where possible. [TODO] continue with other parts of the docs: - Quick start aka Rally step-by-step - Command Line Interface - Rally Task Component - Rally Verification Component - Rally Plugins, Rally Plugins Reference - Contribute to Rally - Request New Features - Project Info [TODO] add 80 symbols margin check similar to what Performance Documentation has Change-Id: I0075be010fcad98272cec0928bcd29ca7b655d33 --- devstack/README.rst | 31 +++++++--- doc/source/db_migrations.rst | 1 - doc/source/index.rst | 3 +- .../install_and_upgrade/db_migrations.rst | 1 + doc/source/install_and_upgrade/index.rst | 24 ++++++++ .../{ => install_and_upgrade}/install.rst | 58 ++++++------------- .../db/sqlalchemy/migrations/README.rst | 15 +++-- 7 files changed, 76 insertions(+), 57 deletions(-) delete mode 120000 doc/source/db_migrations.rst create mode 120000 doc/source/install_and_upgrade/db_migrations.rst create mode 100644 doc/source/install_and_upgrade/index.rst rename doc/source/{ => install_and_upgrade}/install.rst (83%) diff --git a/devstack/README.rst b/devstack/README.rst index d7775778f0..fce244468d 100644 --- a/devstack/README.rst +++ b/devstack/README.rst @@ -1,15 +1,30 @@ -=============================== -Installing Rally using devstack -=============================== +Rally with DevStack all-in-one installation +------------------------------------------- -This directory contains the files necessary to integrate Rally with devstack. +It is also possible to install Rally with DevStack. First, clone the +corresponding repositories: -To configure devstack to run rally edit ``${DEVSTACK_DIR}/local.conf`` file and add:: +.. code-block:: bash + + git clone https://git.openstack.org/openstack-dev/devstack + git clone https://github.com/openstack/rally + +Then, configure DevStack to run Rally. First, create your ``local.conf`` file: + +.. code-block:: bash + + cd devstack + cp samples/local.conf local.conf + +Next, edit local.conf: add the following line to the ``[[local|localrc]]`` +section. + +.. code-block:: bash enable_plugin rally https://github.com/openstack/rally master -to the ``[[local|localrc]]`` section. +Finally, run DevStack as usually: -Run devstack as normal:: +.. code-block:: bash - $ ./stack.sh + ./stack.sh diff --git a/doc/source/db_migrations.rst b/doc/source/db_migrations.rst deleted file mode 120000 index e2e80a0488..0000000000 --- a/doc/source/db_migrations.rst +++ /dev/null @@ -1 +0,0 @@ -../../rally/common/db/sqlalchemy/migrations/README.rst \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index cb39fec17d..92451879d5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -37,13 +37,12 @@ Contents :maxdepth: 2 overview/index - install + install_and_upgrade/index tutorial cli/cli_reference reports plugins plugin/plugin_reference - db_migrations contribute gates feature_requests diff --git a/doc/source/install_and_upgrade/db_migrations.rst b/doc/source/install_and_upgrade/db_migrations.rst new file mode 120000 index 0000000000..34cc0e7a4d --- /dev/null +++ b/doc/source/install_and_upgrade/db_migrations.rst @@ -0,0 +1 @@ +../../../rally/common/db/sqlalchemy/migrations/README.rst \ No newline at end of file diff --git a/doc/source/install_and_upgrade/index.rst b/doc/source/install_and_upgrade/index.rst new file mode 100644 index 0000000000..78f6821081 --- /dev/null +++ b/doc/source/install_and_upgrade/index.rst @@ -0,0 +1,24 @@ +.. + 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. + +========================= +Installation and upgrades +========================= + +.. toctree:: + :glob: + + install + db_migrations diff --git a/doc/source/install.rst b/doc/source/install_and_upgrade/install.rst similarity index 83% rename from doc/source/install.rst rename to doc/source/install_and_upgrade/install.rst index 3a40b47c0d..0a36cc7a3b 100644 --- a/doc/source/install.rst +++ b/doc/source/install_and_upgrade/install.rst @@ -15,14 +15,13 @@ .. _install: -Installation -============ +Installation process +==================== Automated installation ---------------------- -The easiest way to install Rally is by executing its `installation script -`_ +The easiest way to install Rally is by executing its `installation script`_ .. code-block:: bash @@ -37,7 +36,7 @@ the required packages. By default it will install Rally in a virtualenv in ``~/rally`` when run as standard user, or install system wide when run as root. You can -install Rally in a venv by using the option ``--target``: +install Rally in a **venv** by using the option ``--target``: .. code-block:: bash @@ -90,50 +89,24 @@ is already installed in your system. If this is not the case, it will exit, suggesting you the command to issue **as root** in order to install the dependencies. -You also have to set up the **Rally database** after the installation is complete: +You also have to set up the **Rally database** after the installation is +complete: .. code-block:: bash rally-manage db recreate - -Rally with DevStack all-in-one installation -------------------------------------------- - -It is also possible to install Rally with DevStack. First, clone the corresponding repositories: - -.. code-block:: bash - - git clone https://git.openstack.org/openstack-dev/devstack - git clone https://github.com/openstack/rally - -Then, configure DevStack to run Rally. First, create your ``local.conf`` file: - -.. code-block:: bash - - cd devstack - cp samples/local.conf local.conf - -Next, edit local.conf: -add ``enable_plugin rally https://github.com/openstack/rally master`` to ``[[local|localrc]]`` section. - -Finally, run DevStack as usually: - -.. code-block:: bash - - ./stack.sh - +.. include:: ../../../devstack/README.rst Rally & Docker -------------- First you need to install Docker; Docker supplies `installation -instructions for various OSes -`_. +instructions for various OSes`_. You can either use the official Rally Docker image, or build your own -from the Rally source. To do that, change directory to the root directory of the -Rally git repository and run: +from the Rally source. To do that, change directory to the root directory of +the Rally git repository and run: .. code-block:: bash @@ -145,7 +118,7 @@ If you build your own Docker image, substitute ``myrally`` for The Rally Docker image is configured to store local settings and the database in the user's home directory. For persistence of these data, you may want to keep this directory outside of the container. This may -be done by the following steps: +be done via the following steps: .. code-block:: bash @@ -162,7 +135,7 @@ be done by the following steps: likely to work if your home directory has excessively open permissions (e.g., ``0755``), which is not recommended. -All task samples, docs and certification tasks you could find at /opt/rally/. +You can find all task samples, docs and certification tasks at /opt/rally/. Also you may want to save the last command as an alias: .. code-block:: bash @@ -195,4 +168,9 @@ Rally currently has no SELinux policy, which is why it must be run in Permissive mode for certain configurations. If you can help create an SELinux policy for Rally, please contribute! -More about docker: `https://www.docker.com/ `_ +More about docker: https://www.docker.com/ + +.. references: + +.. _installation script: https://raw.githubusercontent.com/openstack/rally/master/install_rally.sh +.. _installation instructions for various OSes: https://docs.docker.com/installation/ diff --git a/rally/common/db/sqlalchemy/migrations/README.rst b/rally/common/db/sqlalchemy/migrations/README.rst index 95353c8669..c6e7792600 100644 --- a/rally/common/db/sqlalchemy/migrations/README.rst +++ b/rally/common/db/sqlalchemy/migrations/README.rst @@ -15,8 +15,8 @@ .. _db_migrations: -Database upgrade/downgrade in Rally -=================================== +Database upgrade in Rally +========================= Information for users --------------------- @@ -55,8 +55,6 @@ DB migration in Rally is implemented via package *alembic*. It is highly recommended to get familiar with it's documentation available by the link_ before proceeding. -.. _link: https://alembic.readthedocs.org - If developer is about to change existing DB schema they should create new DB revision and migration script with the following command @@ -73,8 +71,9 @@ or It will generate migration script -- a file named `_.py` located in `rally/common/db/sqlalchemy/migrations/versions`. -Alembic with parameter ``--autogenerate`` makes some "routine" job for developer, -for example it makes some SQLite compatible batch expressions for migrations. +Alembic with parameter ``--autogenerate`` makes some "routine" job for +developer, for example it makes some SQLite compatible batch expressions for +migrations. Generated script should then be checked, edited if it is needed to be and added to Rally source tree. @@ -82,3 +81,7 @@ and added to Rally source tree. **WARNING** Even though alembic supports schema downgrade, migration scripts provided along with Rally do not contain actual code for downgrade. + +.. references: + +.. _link: https://alembic.readthedocs.org