From 5417b3afcbfb605519c84213b656cd98681101c8 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Fri, 26 Aug 2016 15:39:52 +0200
Subject: [PATCH] doc/python_module.rst: improve

---
 doc/python_module.rst | 53 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/doc/python_module.rst b/doc/python_module.rst
index cebca6e2..3568ba88 100644
--- a/doc/python_module.rst
+++ b/doc/python_module.rst
@@ -1,8 +1,8 @@
-aubio Python module
-===================
+Python module
+=============
 
-Installing with pip
--------------------
+Installing aubio with pip
+-------------------------
 
 .. code-block:: bash
 
@@ -19,10 +19,17 @@ From ``aubio`` source directory, run the following:
     $ ./setup.py build
     $ sudo ./setup.py install
 
-Using the module
-----------------
+Using aubio in python
+---------------------
+
+Once you have python-aubio installed, you should be able to run ``python -c
+"import aubio"``.
 
-To use the python module, simply import aubio:
+A very simple example
+.....................
+
+Here is a very simple script
+to read all the samples from a media file:
 
 .. code-block:: python
 
@@ -32,9 +39,35 @@ To use the python module, simply import aubio:
         s = aubio.source(sys.argv[1], 0, 256)
         while True:
           samples, read = s()
-          print samples
+          #print(samples)
           if read < 256: break
 
-Check out the `python demos for aubio
-<https://github.com/piem/aubio/blob/develop/python/demos/>`_ for more examples.
+Filtering an input sound file
+.............................
+
+Here is a more complete example, `demo_filter.py`_. This files executes the following:
+
+* read an input media file (``aubio.source``)
+
+* filter it using an A-weighting filter (``aubio.digital_filter``)
+
+* write result to a new file (``aubio.sink``)
+
+.. literalinclude:: ../python/demos/demo_filter.py
+   :language: python
+
+More demos
+..........
+
+Check out the `python demos folder`_ for more examples.
+
+Python tests
+------------
+
+A number of `python tests`_ are provided. To run them, use
+``python/tests/run_all_tests``.
+
+.. _python tests folder: https://github.com/aubio/aubio/blob/master/python/tests
+.. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
+.. _demo_filter.py: https://github.com/aubio/aubio/blob/master/python/demos/demo_filter.py
 
-- 
2.11.0