work on documentation

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']

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
+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

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.

doc/source/structure.rst

@@ -6,4 +6,16 @@ Structure
 Plugins
 -------
 
-Requiredness
+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

requirements.txt

@@ -5,3 +5,4 @@ lockfile
 python-daemon
 extras
 GitPython>=0.3.2.RC1
+sphinxcontrib-programoutput 

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',