Function to set DOC_PATH prefix on publish jobs

A Zuul function to generate the sub path needed to publish
documentation. Changes merged on a branch and published tags need to land
at different places. Examples:

  refs/tags/1.24.0 -> /1.24.0/
  REL1_24          -> /REL1_24/
  master           -> /master/ (eventually can be made /latest/)

The documentation 'publish' jobs triggered on Gerrit change-merged
events so we can report back on the Gerrit change that the job has
completed.  The branch is available in Zuul Change objects with the
'refspec' attribute.

Later on, we will be able to publish documentation when a tag is
proposed which is generate a ref-updated event caught by the 'publish'
pipeline. It is only used to generate MediaWiki releases for now. For
those events, the updated reference is the attribute 'ref' in Zuul
Change objects.

Zuul has the ability to tweak parameters sent to Gearman functions (and
thus later on to Jenkins jobs), by registering a function in the
layout.yaml file:
  http://ci.openstack.org/zuul/zuul.html#includes

The set_doc_subpath in /zuul/doc_functions.py carry the logic that
interprets the change-merged and ref-updated events to generate the
proper sub path which is passed to the job as DOC_SUBPATH.

Later on we will then be able to trigger the publish jobs via the
publish pipeline and have documentation generated for each release \O/

Adjust tox.ini to pass positional arguments to nosetest which let one
run a subset of tests:

  tox -epy27 -- tests/test_zuul_doc_functions.py --verbose

Change-Id: I5fbb100294597cbdf029c285fe53b1285a9532c2