From 05d0158c6c847c66f9a3ae804af3affa56101e60 Mon Sep 17 00:00:00 2001 From: Joshua Hesketh Date: Mon, 9 Sep 2013 15:16:08 +1000 Subject: [PATCH] work on documentation --- doc/source/conf.py | 2 +- doc/source/installation.rst | 135 +++++++++++++++++++++++++++++++-- doc/source/intro.rst | 10 +++ doc/source/structure.rst | 14 +++- requirements.txt | 1 + turbo_hipster/worker_server.py | 4 +- 6 files changed, 156 insertions(+), 10 deletions(-) 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 @@ import sys, os # 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 @@ build a report. 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 @@ Typical workflow diagram 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 @@ Structure 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 diff --git a/requirements.txt b/requirements.txt index f7e98fe..f5332af 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,3 +5,4 @@ lockfile python-daemon extras GitPython>=0.3.2.RC1 +sphinxcontrib-programoutput \ No newline at end of file diff --git a/turbo_hipster/worker_server.py b/turbo_hipster/worker_server.py index 60a1941..f5404ae 100755 --- a/turbo_hipster/worker_server.py +++ b/turbo_hipster/worker_server.py @@ -113,8 +113,8 @@ def main(): default= '/etc/turbo-hipster/config.json', help='Path to json config file.') - parser.add_argument('--background', action='store_true', - help='Run in the background.') + parser.add_argument('-b', '--background', action='store_true', + help='Run as a daemon in the background.') parser.add_argument('-p', '--pidfile', default='/var/run/turbo-hipster/' 'turbo-hipster-worker-server.pid',