frank-ci/README.rst

Frank CI
========

Frank CI aims to be a minimal (but smart) continuous integration system. 

To get started you simply deploy from with a WSGI server (e.g NGNIX) and configure
your git repository (github and others) to post a load after each push. 

If your repository includes a top level file called `.frank.yaml` your
frank instance will react uppon the commands found in the file.

Frank commands
--------------

Frank understands the following file format::

   .. text: yaml

    commands:
     - do_this
     - do_that
     - run_function_python
     - deploy_there

    do_this:
      - shell: echo "this"
     
    do_that:
      shell:
       - cd foo
       - touch bar.txt 

    run_function_python:
      python:
       - foo.bar:callable_object


The `commands` is a mandatory list of commnads to excute after each push.
The order of the commands is how the will be executed. 

Following the key `commands` are definitions of each command. Command can
by eith `shell` commands or some callable python object when specified as `python`
and given with full import path `foo.bar` and following callable object after
the collon.


Example 1:
---------- 
The following example will run the tests, build sphinx documentation and 
publish static HTML files via rsync to another server::

    .. text: yaml

    commads:
     - test
     - build_sphinx
     - publish

    test:
      shell:
       - pip install -e .
       - python setup.py test

    build_sphinx:
      shell:
       cwd: docs
       cmd: make html

    publish:
      shell:
       - rsync -avz docs/build/html/ docserver.company.com:/var/www/docs/
   
This example demonstrates running multiple commands after the keyword `shell`.
You can also specify any keyword that the function `subprocess.Popen` accepts.
For example you can specify envirnment variables or the working directroy, as 
in the example with the keyword `cwd`. 

Example 2:
----------
TODO: demonstrate running of python code