From: Paul Brossier <piem@piem.org>
Date: Thu, 6 Mar 2014 17:21:38 +0000 (-0300)
Subject: python/README: improve
X-Git-Tag: 0.4.1~19
X-Git-Url: https://git.aubio.org/?a=commitdiff_plain;h=e794a80f1f5f10ed7d2c2dece62d4e12415b3800;p=aubio.git

python/README: improve
---

diff --git a/python/README b/python/README
index 537f4848..2149d752 100644
--- a/python/README
+++ b/python/README
@@ -1,32 +1,65 @@
 Python aubio module
 ===================
 
-This module wraps the aubio library for python using the numpy module.
+This module wraps the aubio library for Python using the numpy module.
 
-See the [Python/C API Reference
-Manual] (http://docs.python.org/c-api/index.html) and the [Numpy/C API
-Reference](http://docs.scipy.org/doc/numpy/reference/c-api.html)
+Before compiling this module, you must have compiled libaubio.
+
+For more information about how this module works, please refer to the [Python/C
+API Reference Manual] (http://docs.python.org/c-api/index.html) and the
+[Numpy/C API Reference](http://docs.scipy.org/doc/numpy/reference/c-api.html).
 
 Compiling python aubio
 ----------------------
 
-You should be able to build the aubio python module out of the box:
+After libaubio has been build successfully, and provided Python development
+headers and numpy can be found on your system, you should be able to build the
+aubio Python module:
+
+    $ ./setup.py build
+
+To find out more about `setup.py` options:
+
+    $ ./setup.py --help
+
+Installing
+----------
+
+To install the Python module:
 
-    $ python setup.py build
+    $ ./setup.py install
 
-To use the python module without installing it, set PYTHONPATH:
+Using the Python module
+-----------------------
+
+Once the aubio library and the Python module are installed, you will be able to
+import the aubio module:
+
+    $ python
+    [...]
+    >>> import aubio
+    >>>
+
+Alternatively, you may want to use the Python module without installing it by
+setting PYTHONPATH:
 
     $ export PYTHONPATH=$PYTHONPATH:$PWD/`ls -rtd build/lib.* | head -1`:$PWD/tests
 
-And LD_LIBRARY_PATH:
+Similarly, you can use the aubio module without installing libaubio by pointing
+LD_LIBRARY_PATH to the path libaubio can be found at:
 
-    $ export LD_LIBRARY_PATH=$PWD/../build/src
+    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:PWD/../build/src
 
-Or on macosx systems:
+Or on Mac OS X systems, setting DYLD_LIBRARY_PATH:
 
-    $ export DYLD_LIBRARY_PATH=$PWD/../build/src
+    $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$PWD/../build/src
 
-The you should be able to run the tests:
+Testing the Python module
+-------------------------
+
+Once both the C library and the Python module have been built correctly, and
+after you have installed them (or setting the environment variable correctly),
+you should be able to run the tests:
 
     $ ./tests/run_all_tests
 
@@ -34,8 +67,7 @@ And to try out the demos:
 
     $ ./demos/demo_source.wav ~/test.wav
 
-Additional tools
-----------------
-
-To use some of the demo scripts, you will need
-[matplotlib](http://matplotlib.org/).
+You need to install additional modules to run some of the demos. For
+instance, several demos use [matplotlib](http://matplotlib.org/) to draw plots.
+Some more demos use [PySoundCard](https://github.com/bastibe/PySoundCard) to
+play and record sounds.