Restructured documentation
Moved information out of intro.rst and into more specific doc files.
Reorganised index.rst accordingly, and deleted unused files.
Change-Id: I660c5e5e597baddbd1d2d5f60871687b5306834c
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index a0a0732..7c3de7f 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -6,142 +6,111 @@
Installation
============
-Download
---------
+Turbo-hipster is installed directly into your Python ``site-packages``
+directory, and is then run as a service. It is managed using a configuration
+file, which is in .json format.
-Grab a copy from https://github.com/rcbau/turbo-hipster
+Installing turbo-hipster
+------------------------
+1. Turbo-Hipster can be installed directly to your Python ``site-packages``
+directory::
-Install
--------
+ $ sudo python setup.py install
-turbo-hipster is configured to use setup tools for installation if
-you would like to install it to your site-packages use::
+2. Copy the configuration file to a convenient location. By default,
+turbo-hipster will look in ``/etc/turbo-hipster/config.json`` ::
- sudo python setup.py install
+ $ cp -R etc/turbo-hipster /etc/
+3. The Turbo-Hipster configuration file is in .json format. Open the
+``config.json`` configuration file in your preferred editor and modify it
+for your environment::
-Copy config
------------
+ **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 parameters are *name*, which should be the
+ same as the folder containing the plugin module, and
+ *function*, which is the function registered with zuul.
+ 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.
-Place the configuration where you are comfortable managing it. For
-example::
+4. Create a turbo-hipster user:
- cp -R etc/turbo-hipster /etc/
+ $ useradd turbo-hipster
+5. Create the directories listed in the configuration file, and give the
+``turbo-hipster`` user write access::
-Edit config
------------
+ $ mkdir -p /var/log/turbo-hipster/
+ $ chown turbo-hipster:turbo-hipster /var/log/turbo-hipster/
-Turbo-hipsters configuration is currently stored in json format.
-Modify the config.json appropriately::
+ $ mkdir -p /var/lib/turbo-hipster/jobs
+ $ chown turbo-hipster:turbo-hipster /var/lib/turbo-hipster/jobs
- **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 parameters are *name*, which should be the
- same as the folder containing the plugin module, and
- *function*, which is the function registered with zuul.
- 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.
+ $ 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
-Set up
-------
+6. Open the MySQL log rotation configuration file in your preferred text
+editor, and edit it to ensure it is writable by ``other``::
-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.
+ $ vim /etc/logrotate.d/mysql-server
+ # edit create 640 to 644.
-Make sure the required directories as defined by the config.json
-exist and are writeable by your turbo-hipster user::
+.. note::
+ The turbo-hipster source code is also available for download from
+ the `turbo-hipster github page <https://github.com/rcbau/turbo-hipster/>`_
- mkdir -p /var/log/turbo-hipster/
- chown turbo-hipster:turbo-hipster /var/log/turbo-hipster/
+ $ git clone https://github.com/rcbau/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
-
-Edit MySQL's log rotate to ensure it is other writable::
-
- vim /etc/logrotate.d/mysql-server
- # edit create 640 to 644.
-
-
-Start turbo-hipster
--------------------
-
-turbo hipster can be ran by executing::
-
- ./turbo-hipster/worker_server.py
-
-and optionally takes the following parameters::
-
- ./turbo_hipster/worker_server.py --help
- usage: worker_server.py [-h] [-c CONFIG] [-b] [-p PIDFILE]
-
- optional arguments:
- -h, --help show this help message and exit
- -c CONFIG, --config CONFIG
- Path to json config file.
- -b, --background Run as a daemon in the background.
- -p PIDFILE, --pidfile PIDFILE
- PID file to lock during daemonization.
-
-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
+.. note::
+ Debug logging must be configured for turbo-hipster, as it uses the Python
+ logging framework to capture log messages from the task plugin code.
+ To configure debug logging, set the ``debug_log`` configuration
+ setting in the ``config.json`` configuration file.
\ No newline at end of file