Issue #5: add cytoolz.utils.include_dirs to allow other project to …

…use CyToolz' C API.

A minimal example is included in the docstring, although a basic example
should also be in the hosted documentation (whenever it exists).

This should be regarded as an advanced feature for advanced users, so
typical users should not be encouraged to use it.  This is the main
reason `include_dirs` is tucked away in `cytoolz.utils`.

cytoolz/utils.py

@@ -1,5 +1,7 @@
 import doctest
 import inspect
+import os.path
+import cytoolz
 
 
 def raises(err, lamda):
@@ -13,6 +15,36 @@ def raises(err, lamda):
 no_default = '__no__default__'
 
 
+def include_dirs():
+    """ Return a list of directories containing the *.pxd files for ``cytoolz``
+
+    Use this to include ``cytoolz`` in your own Cython project, which allows
+    fast C bindinds to be imported such as ``from cytoolz cimport get``.
+
+    Below is a minimal "setup.py" file using ``include_dirs``:
+
+        from distutils.core import setup
+        from distutils.extension import Extension
+        from Cython.Distutils import build_ext
+
+        import cytoolz.utils
+
+        ext_modules=[
+            Extension("mymodule",
+                      ["mymodule.pyx"],
+                      include_dirs=cytoolz.utils.include_dirs()
+                     )
+        ]
+
+        setup(
+          name = "mymodule",
+          cmdclass = {"build_ext": build_ext},
+          ext_modules = ext_modules
+        )
+    """
+    return os.path.split(cytoolz.__path__[0])
+
+
 # The utilities below were obtained from:
 # https://github.com/cython/cython/wiki/FAQ
 # #how-can-i-run-doctests-in-cython-code-pyx-files