ref: f8bf0c2d28e4a6475e8b2540946ac35a2367e552
parent: 68daf5b853f5bc30f15f57cb548f0a63c6fda781
author: Paul Brossier <piem@piem.org>
date: Wed Oct 31 12:25:09 EDT 2018
[doc] reorganize python doc
--- 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.
-.. midiconv.py
+Contents
+--------
-.. autofunction:: note2midi
+.. toctree::
+ :maxdepth: 1
-.. autofunction:: midi2note
+ py_examples
+ py_datatypes
+ py_io
+ py_utils
-.. autofunction:: freq2note
+Introduction
+------------
-.. autofunction:: note2freq
+This document provides a reference guide. For documentation on how to
+install aubio, see :ref:`python-install`.
-.. slicing.py
+Examples included in this guide and within the code are written assuming
+both `aubio` and `numpy`_ have been imported:
-.. autofunction:: slice_source_at_stamps
+.. code-block:: python
+
+ >>> import aubio
+ >>> import numpy as np
+
+`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`.
+
+.. _numpy: https://www.numpy.org
--- a/doc/python_module.rst
+++ b/doc/python_module.rst
@@ -25,8 +25,8 @@
$ ./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,36 +40,7 @@
$ 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 @@
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