From 2a176d1d0c5bdb1e2c4f732667fbfdd97656ef24 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 12 Jan 2018 16:38:41 -0500 Subject: [PATCH] fix rst formatting Fix some indentation and other markup issues in the RST for the documentation. Change-Id: I921445f7120335510ee7b203a2210737012bcdf2 Signed-off-by: Doug Hellmann --- doc/source/install/development.rst | 72 ++++++++------- doc/source/migration.rst | 143 +++++++++++++++-------------- 2 files changed, 112 insertions(+), 103 deletions(-) diff --git a/doc/source/install/development.rst b/doc/source/install/development.rst index 059c29e6..e56bc725 100644 --- a/doc/source/install/development.rst +++ b/doc/source/install/development.rst @@ -18,8 +18,10 @@ StoryBoard webclient. Installing and Upgrading the API server ======================================= -NOTE: If you are using a Virtual Machine (VM), all commands that begin with -``tox`` will need to be preceeded by ``sudo``. +.. note:: + + If you are using a Virtual Machine (VM), all commands that begin with + ``tox`` will need to be preceeded by ``sudo``. 1. To start the API server, make sure you have the following packages installed locally: @@ -27,13 +29,16 @@ NOTE: If you are using a Virtual Machine (VM), all commands that begin with * libpq-dev * libmysqlclient-dev * python-dev + * MySQL - NOTE: MySQL must be >= 5.6:: + :: - sudo apt-get update - sudo apt-get install libpq-dev libmysqlclient-dev python-dev - sudo apt-get install mysql-server-5.7 #Here you will be asked to set a password - mysql --version + sudo apt-get update + sudo apt-get install libpq-dev libmysqlclient-dev python-dev + sudo apt-get install mysql-server-5.7 #Here you will be asked to set a password + mysql --version + + .. note:: MySQL must be >= 5.6 2. Clone the StoryBoard repository:: @@ -44,13 +49,16 @@ NOTE: If you are using a Virtual Machine (VM), all commands that begin with 3. Add MySQL user and create database: - NOTE: You will need to replace the ``$DB_USER`` with ``root``. - It will prompt for a password; this is - the password you set when you ran - ``sudo apt-get mysql-server-5.6`` in step 1:: + .. note:: - mysql -u $DB_USER -p -e 'DROP DATABASE IF EXISTS storyboard;' - mysql -u $DB_USER -p -e 'CREATE DATABASE storyboard;' + You will need to replace the ``$DB_USER`` with ``root``. It + will prompt for a password; this is the password you set when + you ran ``sudo apt-get mysql-server-5.6`` in step 1. + + :: + + mysql -u $DB_USER -p -e 'DROP DATABASE IF EXISTS storyboard;' + mysql -u $DB_USER -p -e 'CREATE DATABASE storyboard;' 4. Copy the sample configuration file:: @@ -69,7 +77,7 @@ NOTE: If you are using a Virtual Machine (VM), all commands that begin with sudo apt-get install python-pip pip install tox - + 7. Upgrade DB schema to the latest version:: tox -e venv "storyboard-db-manage --config-file ./etc/storyboard.conf upgrade head" @@ -87,12 +95,12 @@ Installing the Javascript-based web client 1. To build and start the web client, you will need this dependency set installed locally: - * Python 2.6 or 2.7 - * Node.js v0.10.29 or newer (see https://nodejs.org/en/download/package-manager/ for more information on getting the right package for your distribution) - * npm v1.3.10 or newer (this will be bundled with Node.js) + * Python 2.6 or 2.7 + * Node.js v0.10.29 or newer (see https://nodejs.org/en/download/package-manager/ for more information on getting the right package for your distribution) + * npm v1.3.10 or newer (this will be bundled with Node.js) - (Ubuntu Trusty packages are sufficient, even though they indicate an older - version. MySQL must be >= 5.6.) + (Ubuntu Trusty packages are sufficient, even though they indicate an older + version. MySQL must be >= 5.6.) 2. Clone the StoryBoard webclient:: @@ -101,24 +109,20 @@ Installing the Javascript-based web client cd storyboard-webclient -Do one of the following that applies to you: +3. Do **one** of the following that applies to you. - 3a. Run a local development server, which uses the localhost API:: + a. Run a local development server, which uses the localhost API:: - tox -egrunt_no_api -- serve + tox -egrunt_no_api -- serve -or... + b. Run a local development server, which binds to a specific IP and + consumes the localhost API:: - 3b. Run a local development server, which binds to a specific IP and - consumes the localhost API:: + tox -egrunt_no_api -- serve --hostname 0.0.0.0 - tox -egrunt_no_api -- serve --hostname 0.0.0.0 + c. Run a local development server, which uses the production API:: -or... - - 3c. Run a local development server, which uses the production API:: - - tox -egrunt_no_api -- serve:prod + tox -egrunt_no_api -- serve:prod Make user an admin - current bug @@ -208,8 +212,10 @@ Optional steps: Seed database with base data Optional steps: Set up the notifications daemon =============================================== -NOTE: If you followed the "Launch the development VM" instuctions -above, this step is unnecessary. +.. note:: + + If you followed the "Launch the development VM" instuctions above, + this step is unnecessary. 1. Install rabbitmq on your development machine:: diff --git a/doc/source/migration.rst b/doc/source/migration.rst index 2853890a..f7314082 100644 --- a/doc/source/migration.rst +++ b/doc/source/migration.rst @@ -26,109 +26,110 @@ Test Migration 1. Obtain a StoryBoard instance -First you'll need superuser permissions on a StoryBoard instance. Unless -you are infra-core or Zara or SotK, the best way to do this is to spin -up your own test instance in a VM or somewhere. + First you'll need superuser permissions on a StoryBoard instance. Unless + you are infra-core or Zara or SotK, the best way to do this is to spin + up your own test instance in a VM or somewhere. -There are instructions on how to do that [here][0]. I won't go into detail -here on the ins and outs of getting set up. When you have an up-to-date -database you'll need to log in via the webclient. Upon successfully logging -in, connect to your database with the mysql command line client, providing -your password as prompted: + There are instructions on how to do that in :doc:`/install/development`. + I won't go into detail + here on the ins and outs of getting set up. When you have an up-to-date + database you'll need to log in via the webclient. Upon successfully logging + in, connect to your database with the mysql command line client, providing + your password as prompted:: - mysql -u $YOUR_DB_USER -p + mysql -u $YOUR_DB_USER -p -Then run the following: + Then run the following:: - connect $YOUR_DB_NAME; - update users set is_superuser=1; + connect $YOUR_DB_NAME; + update users set is_superuser=1; -This will make every user that has so far logged in to have superuser -permissions. + This will make every user that has so far logged in to have superuser + permissions. -[0]: https://docs.openstack.org/infra/storyboard/install/development.html + * (optional) Obtain a sanitised dump of the production database -1.1 (optional) Obtain a sanitised dump of the production database + If you want to test migrating against production data, you'll need that + data. The way to obtain this is to ask an infra core nicely. -If you want to test migrating against production data, you'll need that -data. The way to obtain this is to ask an infra core nicely. + You can use the provided .sql file to recreate the production database + in your local instance:: -You can use the provided .sql file to recreate the production database -in your local instance: + mysql -u $YOUR_DB_USER -p < /path/to/db/dump.sql - mysql -u $YOUR_DB_USER -p < /path/to/db/dump.sql + .. warning:: -> WARNING: This database will have the name `storyboard`, and will -> obliterate the contents of any database you already have with the -> same name. + This database will have the name `storyboard`, and will obliterate + the contents of any database you already have with the same name. 2. Create the StoryBoard project -Log in to the webclient for your StoryBoard instance. When logged in, -click the "Create New..." button, and pick "Project". Give the project -a name (in storyboard.o.o this will match the git repository name, so -you may as well use that) and a description. + Log in to the webclient for your StoryBoard instance. When logged in, + click the "Create New..." button, and pick "Project". Give the project + a name (in storyboard.o.o this will match the git repository name, so + you may as well use that) and a description. -When you are happy with the name and description, and both are outlined -in green, click "Create Project". + When you are happy with the name and description, and both are outlined + in green, click "Create Project". 3. Migrate! - You can do this with the following command: + + You can do this with the following command:: tox -e venv "storyboard-migrate --config-file etc/storyboard.conf --from-project $PROJECT_IN_LAUNCHPAD --to-project $PROJECT_IN_STORYBOARD" -Here, `$PROJECT_IN_LAUNCHPAD` should be replaced by the name of the -project in Launchpad, for example `monasca`. Similarly, -`$PROJECT_IN_STORYBOARD` should be replaced the name of the project -you are importing into in StoryBoard, for example `openstack/monasca`. + Here, `$PROJECT_IN_LAUNCHPAD` should be replaced by the name of the + project in Launchpad, for example `monasca`. Similarly, + `$PROJECT_IN_STORYBOARD` should be replaced the name of the project + you are importing into in StoryBoard, for example `openstack/monasca`. -Then you must wait for some time to pass whilst the project is -migrated. You can watch the output if you like. Sometimes it will -crash with a traceback saying the database object already exists. + Then you must wait for some time to pass whilst the project is + migrated. You can watch the output if you like. Sometimes it will + crash with a traceback saying the database object already exists. -If this happens, then your migration test has FAILED and you need -to go shout at SotK to fix this bug (or fix it yourself if you have -the spare time to help). + If this happens, then your migration test has FAILED and you need + to go shout at SotK to fix this bug (or fix it yourself if you have + the spare time to help). -Sometimes it might break in other ways for some reason. If this -happens, then your migration test has FAILED and you have found a -new and exciting bug. Report it in #storyboard and maybe on -StoryBoard somewhere and try to fix it if you like. + Sometimes it might break in other ways for some reason. If this + happens, then your migration test has FAILED and you have found a + new and exciting bug. Report it in #storyboard and maybe on + StoryBoard somewhere and try to fix it if you like. 4. Check everything went smoothly -At this point you have successfully run a migration. You now need to -check that you haven't triggered any of the migration issues we know -about currently. + At this point you have successfully run a migration. You now need to + check that you haven't triggered any of the migration issues we know + about currently. -Check branches as described in 3.1, and also check that you can view -the project page in the webclient. Page through the stories to make -sure that none of them have content that breaks the webclient. + Check branches as described in 3.1, and also check that you can view + the project page in the webclient. Page through the stories to make + sure that none of them have content that breaks the webclient. -Check that you can view + Check that you can view the URL: - http://localhost:9000/api/v1/stories?project_id=$YOUR_PROJECT_ID_HERE + http://localhost:9000/api/v1/stories?project_id=$YOUR_PROJECT_ID_HERE -in a web browser. If there is trouble for your browser in rendering -that then one of the stories has a non-unicode character in it which -will ruin StoryBoard's day. + in a web browser. If there is trouble for your browser in rendering + that then one of the stories has a non-unicode character in it which + will ruin StoryBoard's day. -If any of these checks don't succeed, then your migration test has -FAILED. + If any of these checks don't succeed, then your migration test has + FAILED. -If they all succeed, then maybe so has your migration. Test everything -you feel like testing, check some of the stories to make sure they look -sane. Beware of things that look like a huge mess but are actually just -our markdown parser mangling logs that weren't indented by the bug -submitter. These aren't an issue but will probably make someone sad. + If they all succeed, then maybe so has your migration. Test everything + you feel like testing, check some of the stories to make sure they look + sane. Beware of things that look like a huge mess but are actually just + our markdown parser mangling logs that weren't indented by the bug + submitter. These aren't an issue but will probably make someone sad. -Assuming you tested against production data and everything checked out, -the project should be ready to migrate for real. If it wasn't tested -against production data, now would be the time test against it as you may -discover other bugs. + Assuming you tested against production data and everything checked out, + the project should be ready to migrate for real. If it wasn't tested + against production data, now would be the time test against it as you may + discover other bugs. The Migration Process --------------------- @@ -149,9 +150,11 @@ Recently Migrated about where to file bugs now, then go to the 'Bugs' section and set the 'bugs are tracked' radio button to the 'somewhere else' option. - NOTE: Launchpad does not close open bugs or note the new location that - people should make comments and updates at which is why it is important - to communicate to users, operators, and contributors that you've migrated + .. note:: + + Launchpad does not close open bugs or note the new location that + people should make comments and updates at which is why it is important + to communicate to users, operators, and contributors that you've migrated Q & A -----