work on documentation
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 22c7990..8158f9c 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -25,7 +25,7 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.graphviz']
+extensions = ['sphinx.ext.graphviz', 'sphinxcontrib.programoutput']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index def7cc6..08272c0 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -1,9 +1,132 @@
+:title: Installation
+
+.. _gearman: http://gearman.org/
+.. _zuul: http://ci.openstack.org/zuul/
+
Installation
============
-1. Download
-2. Copy config
-3. Edit config
-4. Make dirs
-5. Chmod them
-6. Start using daemon
\ No newline at end of file
+Download
+--------
+
+Grab a copy from https://github.com/rcbau/turbo-hipster
+
+
+Install
+-------
+
+turbo-hipster is configured to use setup tools for installation if
+you would like to install it to your site-packages use::
+
+ sudo python setup.py install
+
+
+Copy config
+-----------
+
+Place the configuration where you are comfortable managing it. For
+example::
+
+ cp -R etc/turbo-hipster /etc/
+
+
+Edit config
+-----------
+
+Turbo-hipsters configuration is currently stored in json format.
+Modify the config.json appropriately:
+
+ **zuul_server**
+ A dictionary containing details about how to communicate
+ with zuul
+ **git_url**
+ The publicly accessible protocol and URI from where
+ to clone projects and zuul_ references from. For
+ example::
+ http://review.openstack.org/p/
+ or::
+ git://review.example.org
+ **gearman_host**
+ The host of gearman_. zuul talks to its workers via
+ the gearman protocol and while it comes with a built-
+ in gearman server you can use a separate one.
+ **gearman_port**
+ The port that gearman listens on.
+ **debug_log**
+ A path to the debug log. Turbo-hipster will attempt to create
+ the file but must have write permissions.
+ **jobs_working_dir**
+ Each job will likely need to write out log and debug
+ information. This defines where turbo-hipster will do that.
+ **git_working_dir**
+ turbo-hipster needs to take a copy of the git tree of a
+ project to work from. This is the path it'll clone into and
+ work from (if needed).
+ **pip_download_cache**
+ Some of turbo-hipsters task plugins download requirements
+ for projects. This is the cache directory used by pip.
+ **plugins**
+ A list of enabled plugins and their settings in a dictionary.
+ The only required parameter is *name* which should be the
+ same as the folder containing the plugin module. Any other
+ parameters are specified by the plugin themselves as
+ required.
+ **publish_logs**
+ Log results from plugins can be published using multiple
+ methods. Currently only a local copy is fully implemented.
+ **type**
+ The type of protocol to copy the log to. eg 'local'
+ **path**
+ A type specific parameter defining the local location
+ destination.
+ **prepend_url**
+ What to prepend to the path when sending the result
+ URL back to zuul. This can be useful as you may want
+ to use a script to authenticate against a swift
+ account or to use *laughing_spice* to format the logs
+ etc.
+
+
+Set up
+------
+
+You probably want to create a user to run turbo-hipster as. This user
+will need to write to all of the directories specified in
+config.json.
+
+Make sure the required directories as defined by the config.json
+exist and are writeable by your turbo-hipster user::
+
+ mkdir -p /var/log/turbo-hipster/
+ chown turbo-hipster:turbo-hipster /var/log/turbo-hipster/
+
+ mkdir -p /var/lib/turbo-hipster/jobs
+ chown turbo-hipster:turbo-hipster /var/lib/turbo-hipster/jobs
+
+ mkdir -p /var/lib/turbo-hipster/git
+ chown turbo-hipster:turbo-hipster /var/lib/turbo-hipster/git
+
+ mkdir -p /var/cache/pip
+ chown turbo-hipster:turbo-hipster /var/cache/pip
+
+
+Start turbo-hipster
+-------------------
+
+turbo hipster can be ran by executing::
+
+ ./turbo-hipster/worker_server.py
+
+and optionally takes the following parameters:
+
+ .. program-output:: ../../turbo_hipster/worker_server.py --help
+
+By default turbo-hipster will look for
+*/etc/turbo-hipster/config.json*
+
+Alternatively turbo-hipster can be launched by init.d using the
+included etc/init.d/turbo-hipster script::
+
+ sudo cp etc/init.d/turbo-hipster /etc/init.d/
+ sudo update-rc.d turbo-hipster defaults
+ sudo service turbo-hipster start
diff --git a/doc/source/intro.rst b/doc/source/intro.rst
index 79ee11c..c580182 100644
--- a/doc/source/intro.rst
+++ b/doc/source/intro.rst
@@ -20,6 +20,9 @@
Typical workflow diagram
------------------------
+**clearly this needs a lot of work, however I believe the structure
+is mostly there...**
+
.. graphviz::
digraph overview {
@@ -107,3 +110,10 @@
ths003 -> gm003;
}
+
+zuul integration
+----------------
+
+Explain how zuul triggers builds and gates etc and how turbo-hipster
+responds to them. Most of this is in the zuul documentation so don't
+duplicate.
diff --git a/doc/source/structure.rst b/doc/source/structure.rst
index 26fcd7b..c203466 100644
--- a/doc/source/structure.rst
+++ b/doc/source/structure.rst
@@ -6,4 +6,16 @@
Plugins
-------
-Requiredness
\ No newline at end of file
+A little bit about plugins to come here soon.
+
+ - You need to configure it in config.json
+ - Folder name must be the same as 'name'
+ - You probably want to specify a gate in the config
+ - see something (introduction?) about gates and how turbo-hipster
+ uses them
+ - Each plugin has a task.py with a Runner class
+ - Responsible for registering functions
+ - handling jobs
+ - checking for errors
+ - building reports
+ - publishing them according to configuration