frank-ci/docs/frank.rst

Frank can be configured using the following yaml::
    .frank.yml

    commads:
     - test
     - deploy
     - publish

    newtag:
         - python:
           - frank.actions:detect_new_tag

    deploy:
     - cmd
     - runif
       - test
       - newtag

    publish:
     - shell:
       - cd docs; make html
     - python:
       - frank.actions:recursive_copy

The sections commands is a simple list of command you would
like to define.
This section is optional. It's main purpose is for you to decalre
which commands frank should execute upon recieving a load.

Each command is a dictionary with the following possible keys::

    cmd_name:
      - cmd  # not mandatory if you include it in the list of commands
      - runif # a conditional to determine whether to run or skip the command
              # it can contain multiple directives which can be python
              # code to execute
              # or shell code


For example, let's say you would like to build the sphinx documentation
of your project after every push. You start by defining a command
build_docs in the following way::

   build_docs:
    - cmd
    - shell:
      - cd docs
      - make html

You could also specify::

   build_docs:
    - cmd
    - shell: cd docs; make html

or::

   build_docs:
    - shell:
      - cwd: docs
      - cmd: make html


This tells that `build_docs` is a command that executes after every push.
It will execute a shell and will run the shell commands
`cd docs; make html`. Pretty straight forward!

Now, let's refine. Suppose we want to build the docs only if the docs changed,
thus ignoring completely, changes in the embeded docs strings*::

   build_docs:
    - cmd
    - runif:
      - shell:
        - git --no-pager diff --name-status HEAD~1 | grep -v docs
    - shell: cd docs; make html

Now, the command will run if the latest git commit have changed the docs
directory. Since the grep command will return exit with 1.
Alternatively, the conditional to run can be some python code that returns
True or False. Here is how to specify this:

   build_docs:
    - cmd
    - runif:
      - python: frank.githubparsers:detect_changes_in_docs
    - shell: cd docs; make html

This, will invoke the method ``detect_changes_in_docs`` which is
found in the module `frank.githubparsers`.
If this function will return True the shell command will execute.
If the methods takes some arguments, they could also be given.
Suppose the function is called `detect_changes_in` and this function
takes a single paramter called path we can configure the
build_docs command in the following way::

   build_docs:
    - cmd
    - runif:
     - python:
      - function: frank.githubparsers:detect_changes_in
      - args:
       - path: docs

note::
  
  This is probably a lame idea, but it's good for demonstration.
  So, do write doc-strings, and do build  your docs often.