From f8bf0c2d28e4a6475e8b2540946ac35a2367e552 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Wed, 31 Oct 2018 16:25:09 +0100
Subject: [PATCH] [doc] reorganize python doc

---
 doc/python.rst        | 40 +++++++++++++++++++++++++++++++++-------
 doc/python_module.rst | 34 ++--------------------------------
 2 files changed, 35 insertions(+), 39 deletions(-)

diff --git a/doc/python.rst b/doc/python.rst
index 038055a1..0664cc59 100644
--- a/doc/python.rst
+++ b/doc/python.rst
@@ -7,23 +7,49 @@
 ..
    we follow numpy type docstrings, see:
    https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+..
+   note: we do not import aubio's docstring, which will be displayed from an
+   interpreter.
+
+.. .. automodule:: aubio
+
 
 .. _python:
 
 Python documentation
 ====================
 
+This module provides a number of classes and functions for the analysis of
+music and audio signals.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   py_examples
+   py_datatypes
+   py_io
+   py_utils
 
-.. midiconv.py
+Introduction
+------------
 
-.. autofunction:: note2midi
+This document provides a reference guide. For documentation on how to
+install aubio, see :ref:`python-install`.
 
-.. autofunction:: midi2note
+Examples included in this guide and within the code are written assuming
+both `aubio` and `numpy`_ have been imported:
 
-.. autofunction:: freq2note
+.. code-block:: python
 
-.. autofunction:: note2freq
+    >>> import aubio
+    >>> import numpy as np
 
-.. slicing.py
+`Changed in 0.4.8` :  Prior to this version, almost no documentation was
+provided with the python module. This version adds documentation for some
+classes, including :class:`fvec`, :class:`cvec`, :class:`source`, and
+:class:`sink`.
 
-.. autofunction:: slice_source_at_stamps
+.. _numpy: https://www.numpy.org
diff --git a/doc/python_module.rst b/doc/python_module.rst
index d552dea0..e008a315 100644
--- a/doc/python_module.rst
+++ b/doc/python_module.rst
@@ -25,8 +25,8 @@ From ``aubio`` source directory, run the following:
     $ ./setup.py build
     $ sudo ./setup.py install
 
-Using aubio in python
----------------------
+Checking your installation
+--------------------------
 
 Once the python module is installed, its version can be checked with:
 
@@ -40,35 +40,6 @@ The command line `aubio` is also installed:
 
     $ aubio -h
 
-A simple example
-................
-
-Here is a :download:`simple script <../python/demos/demo_source_simple.py>`
-that reads all the samples from a media file:
-
-.. literalinclude:: ../python/demos/demo_source_simple.py
-   :language: python
-
-Filtering an input sound file
-.............................
-
-Here is a more complete example, :download:`demo_filter.py
-<../python/demos/demo_filter.py>`. This files executes the following:
-
-* read an input media file (``aubio.source``)
-
-* filter it using an `A-weighting <https://en.wikipedia.org/wiki/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
 ------------
@@ -76,6 +47,5 @@ Python tests
 A number of `python tests`_ are provided. To run them, use
 ``python/tests/run_all_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
 .. _python tests: https://github.com/aubio/aubio/blob/master/python/tests
-- 
2.11.0