document volume path construction

docs/source/volumes.rst

@@ -25,6 +25,41 @@ The expectation is that this directory will map to a different file system.
     | If ``koji-1.13.0-1`` is on the volume named "test", its path will be:
     | /mnt/koji/vol/test/packages/koji/1.13.0/1
 
+
+Constructing the path
+---------------------
+
+If you are using the Koji python api, things should **just work**.
+
+::
+
+    >>> import koji
+    >>> mykoji = koji.get_profile_module('mykoji')
+    >>> opts = mykoji.grab_session_options(mykoji.config)
+    >>> session = mykoji.ClientSession(mykoji.config.server, opts)
+    >>> binfo = session.getBuild('test-1-1')
+    >>> binfo['volume_name']
+    'DEFAULT'
+    >>> mykoji.pathinfo.build(binfo)
+    '/mnt/koji/packages/test/1/1'
+    >>> binfo = session.getBuild('fake-1.0-21')
+    >>> binfo['volume_name']
+    'vol3'
+    >>> mykoji.pathinfo.build(binfo)
+    '/mnt/koji/vol/vol3/packages/fake/1.0/21'
+
+If you are not using the Koji python api, then you may need to do a little
+work.
+
+If you have build data from a Koji instance, then that data should include
+the volume. Hub calls that return build data include ``volume_name`` and
+``volume_id`` fields in their return.
+
+If the volume is ``DEFAULT``, then the path is the "normal" path. Otherwise,
+the ``/vol/<volume_name>/`` needs to be inserted after the top directory
+(normally /mnt/koji).
+
+
 Adding a new volume
 -------------------