Update developer documentation

Change-Id: Ib28f48bad93d119d0aa44324e9cb0fe7c1a12754

README.rst

@@ -33,31 +33,3 @@ All OpenStack projects use Gerrit for code reviews.
 A good reference for that is here:
 
   https://wiki.openstack.org/wiki/GerritWorkflow
-
-------------------------------
-Getting Started as a Developer
-------------------------------
-
-Storyboard has two components: this API server, and the
-Javascript-based web client.  To start the API server, make sure you
-have the following packages installed locally:
-
-* libpq-dev
-* libmysqlclient-dev
-
-Then run::
-
-  mysql -u $DB_USER -p $DB_PASSWORD -e 'DROP DATABASE IF EXISTS storyboard;'
-  mysql -u $DB_USER -p $DB_PASSWORD -e 'CREATE DATABASE storyboard;'
-  cp ./etc/storyboard.conf.sample ./etc/storyboard.conf
-
-Edit ./etc/storyboard.conf and set the ``connection`` parameter in the
-``[database]`` section.  Then run::
-
-  tox -e venv "storyboard-db-manage --config-file ./etc/storyboard.conf upgrade head"
-  tox -e venv "storyboard-api --config-file ./etc/storyboard.conf"
-
-Then to use the web client, clone the repo and follow the instructions
-in the README::
-
-  git clone https://git.openstack.org/openstack-infra/storyboard-webclient

doc/source/index.rst

@@ -29,11 +29,24 @@ contribute to the project.
 Table of contents
 =================
 
-.. toctree::
-   :maxdepth: 2
 
-   install/index
-   contributing
+Installation guides
+-------------------
+.. toctree::
+   :maxdepth: 1
+
+   install/manual
+   install/development
+
+
+Developer docs
+--------------
+
+.. toctree::
+    :maxdepth: 1
+
+    contributing
+    webclient
 
 
 Client API Reference

doc/source/install/development.rst

@@ -2,8 +2,70 @@
  Installing and Running the Development Version
 ================================================
 
-See `webclient readme file`_ for details.
+Storyboard has two components: this API server, and the
+Javascript-based web client.
 
-More details will be added later...
 
-.. _webclient readme file: https://git.openstack.org/cgit/openstack-infra/storyboard-webclient/tree/README.md
+Installing the API server
+=========================
+
+1. To start the API server, make sure you have the following packages installed 
+   locally:
+
+   * libpq-dev
+   * libmysqlclient-dev
+
+
+2. Clone storyboard::
+
+	git clone https://git.openstack.org/openstack-infra/storyboard
+	cd storyboard
+
+
+3. Add MySQL user and create database::
+
+   	mysql -u $DB_USER -p $DB_PASSWORD -e 'DROP DATABASE IF EXISTS storyboard;'
+   	mysql -u $DB_USER -p $DB_PASSWORD -e 'CREATE DATABASE storyboard;'
+
+
+4. Copy the sample configuration file::
+
+	cp ./etc/storyboard.conf.sample ./etc/storyboard.conf
+
+
+5. Edit ``./etc/storyboard.conf`` and set the ``connection`` parameter in 
+   the ``[database]`` section.
+
+
+6. Upgrade DB schema to the latest version::
+
+	tox -e venv "storyboard-db-manage --config-file ./etc/storyboard.conf upgrade head"
+
+
+7. Start the API server::
+
+	tox -e venv "storyboard-api --config-file ./etc/storyboard.conf"
+
+
+Installing the Javascript-based web client
+==========================================
+
+1. To build and start the web client, make sure you have the following packages 
+   installed locally:
+
+   * Xvfb
+   * GCC 4.2 or newer
+   * Python 2.6 or 2.7
+   * GNU Make 3.81 or newer
+   * libexecinfo (FreeBSD and OpenBSD only)
+
+
+2. Clone storyboard::
+
+   	git clone https://git.openstack.org/openstack-infra/storyboard-webclient
+   	cd storyboard-webclient
+
+
+3. Run a local development server::
+
+   	tox -egrunt_no_api server

doc/source/install/index.rst

@@ -1,11 +0,0 @@
-.. _install:
-
-======================
- Installing Storyboard
-======================
-
-.. toctree::
-   :maxdepth: 2
-
-   development
-   manual

doc/source/webclient.rst

@@ -0,0 +1,74 @@
+Web Client Commands
+====================
+
+Using tox:
+----------
+
+* Run the test suite::
+  	
+  	tox -egrunt test
+
+
+* Run a local development server::
+
+  	tox -egrunt server
+
+
+* Run a local development server without the API::
+
+  	tox -egrunt_no_api server`
+
+
+* Package the distro::
+
+  	tox -egrunt build
+
+
+Using grunt directly within virtual environment
+-----------------------------------------------
+
+* Activate virtual environment::
+  	
+  	source .tox/grunt/bin/activate
+
+
+* Update/refresh the javascript build and runtime dependencies::
+
+  	npm prune
+  	npm install
+  	bower prune
+  	bower install
+
+
+* Run a local development server with API and web client::
+
+  	grunt server
+
+
+* Run the test suite::
+
+  	grunt test
+
+
+* Package the distro::
+
+  	grunt build
+
+
+* Bootstrap your database::
+
+  ./bin/api.sh create-db`
+
+
+* Migrate the database::
+
+  	./bin/api.sh migrate-db
+
+
+* Start the API::
+
+  	./bin/api.sh start
+
+* Stop the API::
+
+  	./bin/api.sh stop