Index: doc/about.rst
===================================================================
--- doc/about.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/about.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -60,5 +60,5 @@
 -------
 
-aubio is a `free <http://www.debian.org/intro/free>`_ and `open source
+aubio is a `free <https://www.debian.org/intro/free>`_ and `open source
 <http://www.opensource.org/docs/definition.php>`_ software; **you** can
 redistribute it and/or modify it under the terms of the `GNU
Index: doc/aubio.txt
===================================================================
--- doc/aubio.txt	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/aubio.txt	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -99,5 +99,11 @@
 NOTES
 
-  The "note" command accepts all common options and no additional options.
+  The following additional options can be used with the "notes" subcommand.
+
+  -s <value>, --silence <value>  silence threshold, in dB (default: -70)
+
+  -d <value>, --release-drop <value>  release drop level, in dB. If the level
+  drops more than this amount since the last note started, the note will be
+  turned off (default: 10).
 
 MFCC
Index: doc/aubiocut.txt
===================================================================
--- doc/aubiocut.txt	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/aubiocut.txt	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -51,4 +51,6 @@
   each slice (default 0).
 
+  --create-first  Alway create first slice.
+
   -h, --help  Print a short help message and exit.
 
Index: doc/aubiomfcc.txt
===================================================================
--- doc/aubiomfcc.txt	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/aubiomfcc.txt	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -52,5 +52,5 @@
   url:
 
-  http://cobweb.ecn.purdue.edu/~malcolm/interval/1998-010/ (see file mfcc.m)
+  https://engineering.purdue.edu/~malcolm/interval/1998-010/ (see file mfcc.m)
 
 SEE ALSO
Index: doc/aubionotes.txt
===================================================================
--- doc/aubionotes.txt	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/aubionotes.txt	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -7,5 +7,5 @@
   aubionotes [[-i] source]
              [-r rate] [-B win] [-H hop]
-             [-O method] [-t thres]
+             [-O method] [-t thres] [-d drop]
              [-p method] [-u unit] [-l thres]
              [-T time-format]
@@ -69,4 +69,8 @@
   loudest ones. A value of -90.0 would select all onsets. Defaults to -90.0.
 
+  -d, --release-drop  Set the release drop threshold, in dB. If the level drops
+  more than this amount since the last note started, the note will be turned
+  off. Defaults to 10.
+
   -T, --timeformat format  Set time format (samples, ms, seconds). Defaults to
   seconds.
@@ -88,5 +92,6 @@
 PITCH METHODS
 
-  Available methods: default, schmitt, fcomb, mcomb, specacf, yin, yinfft.
+  Available methods: default, schmitt, fcomb, mcomb, specacf, yin, yinfft,
+  yinfast.
 
   See aubiopitch(1) for details about these methods.
Index: doc/aubiopitch.txt
===================================================================
--- doc/aubiopitch.txt	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/aubiopitch.txt	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -121,4 +121,10 @@
   University of London, London, UK, 2006.
 
+  yinfast  YIN algorithm (accelerated)
+
+  An optimised implementation of the YIN algorithm, yielding results identical
+  to the original YIN algorithm, while reducing its computational cost from
+  O(n^2) to O(n log(n)).
+
 SEE ALSO
 
Index: doc/conf.py
===================================================================
--- doc/conf.py	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/conf.py	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -30,5 +30,12 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc']
+extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc',
+        'sphinx.ext.napoleon', 'sphinx.ext.intersphinx']
+
+autodoc_member_order = 'groupwise'
+
+intersphinx_mapping = {
+        'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+        }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -46,5 +53,5 @@
 # General information about the project.
 project = u'aubio'
-copyright = u'2016, Paul Brossier'
+copyright = u'2018, Paul Brossier'
 
 # The version info for the project you're documenting, acts as replacement for
Index: doc/debian_packages.rst
===================================================================
--- doc/debian_packages.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/debian_packages.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -10,5 +10,5 @@
 ``git-buildpackage`` to build from the git repository. For instance:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ git clone git://anonscm.debian.org/collab-maint/aubio.git
Index: doc/develop.rst
===================================================================
--- doc/develop.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/develop.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -1,6 +1,6 @@
 .. _develop:
 
-Developping with aubio
-======================
+Developing with aubio
+=====================
 
 Here is a brief overview of the C library.
Index: doc/index.rst
===================================================================
--- doc/index.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/index.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -71,4 +71,5 @@
    installing
    python_module
+   python
    cli
    develop
Index: doc/installing.rst
===================================================================
--- doc/installing.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/installing.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -32,5 +32,5 @@
     sudo ./waf install
 
-- :ref:`install python-aubio from source <python>`::
+- :ref:`install python-aubio from source <python-install>`::
 
     # from git
@@ -46,5 +46,5 @@
     pip install -v .
 
-- :ref:`install python-aubio from a pre-compiled binary <python>`::
+- :ref:`install python-aubio from a pre-compiled binary <python-install>`::
 
       # conda [osx, linux, win]
Index: doc/py_analysis.rst
===================================================================
--- doc/py_analysis.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_analysis.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,15 @@
+.. currentmodule:: aubio
+.. default-domain:: py
+
+Analysis
+--------
+
+.. members of generated classes are not shown
+
+.. autoclass:: onset
+
+.. autoclass:: pitch
+
+.. autoclass:: tempo
+
+.. autoclass:: notes
Index: doc/py_datatypes.rst
===================================================================
--- doc/py_datatypes.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_datatypes.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,43 @@
+.. default-domain:: py
+.. currentmodule:: aubio
+
+Data-types
+----------
+
+This section contains the documentation for :data:`float_type`,
+:class:`fvec`, and :class:`cvec`.
+
+.. defined in rst only
+
+.. data:: float_type
+
+    A string constant describing the floating-point representation used in
+    :class:`fvec`, :class:`cvec`, and elsewhere in this module.
+
+    Defaults to `"float32"`.
+
+    If `aubio` was built specifically with the option `--enable-double`, this
+    string will be defined to `"float64"`. See :ref:`py-doubleprecision` in
+    :ref:`python-install` for more details on building aubio in double
+    precision mode.
+
+    .. rubric:: Examples
+
+    >>> aubio.float_type
+    'float32'
+    >>> numpy.zeros(10).dtype
+    'float64'
+    >>> aubio.fvec(10).dtype
+    'float32'
+    >>> np.arange(10, dtype=aubio.float_type).dtype
+    'float32'
+
+.. defined in `python/lib/aubio/__init__.py`
+
+.. autoclass:: fvec
+  :members:
+
+.. defined in `python/ext/py-cvec.h`
+
+.. autoclass:: cvec
+  :members:
Index: doc/py_examples.rst
===================================================================
--- doc/py_examples.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_examples.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,42 @@
+.. default-domain:: py
+.. currentmodule:: aubio
+
+Examples
+--------
+
+Below is a short selection of examples using the aubio module.
+
+Read a sound file
+.................
+
+Here is a simple script, :download:`demo_source_simple.py
+<../python/demos/demo_source_simple.py>` that reads all the samples from a
+media file using :class:`source`:
+
+.. literalinclude:: ../python/demos/demo_source_simple.py
+   :language: python
+
+Filter a sound file
+...................
+
+Here is another example, :download:`demo_filter.py
+<../python/demos/demo_filter.py>`, which applies a filter to a sound file
+and writes the filtered signal in another file:
+
+* read audio samples from a file with :class:`source`
+
+* filter them using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
+  filter using :class:`digital_filter`
+
+* write the filtered samples to a new file with :class:`sink`.
+
+.. literalinclude:: ../python/demos/demo_filter.py
+   :language: python
+
+More examples
+.............
+
+For more examples showing how to use other components of the module, see
+the `python demos folder`_.
+
+.. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
Index: doc/py_io.rst
===================================================================
--- doc/py_io.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_io.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,118 @@
+.. currentmodule:: aubio
+.. default-domain:: py
+
+Input/Output
+------------
+
+This section contains the documentation for two classes:
+:class:`source`, to read audio samples from files, and :class:`sink`,
+to write audio samples to disk.
+
+.. defined in `python/ext`
+
+..
+   Note: __call__ docstrings of objects defined in C must be written
+   specifically in RST, since there is no known way to add them to
+   their C implementation.
+
+..
+   TODO: remove special-members documentation
+
+.. defined in py-source.c
+
+.. autoclass:: source
+  :members:
+  :special-members: __enter__
+  :no-special-members:
+
+  .. function:: __call__()
+
+    Read at most `hop_size` new samples from self, return them in
+    a tuple with the number of samples actually read.
+
+    The returned tuple contains:
+
+    - a vector of shape `(hop_size,)`, filled with the `read` next
+      samples available, zero-padded if `read < hop_size`
+    - `read`, an integer indicating the number of samples read
+
+    If opened with more than one channel, the frames will be
+    down-mixed to produce the new samples.
+
+    :returns: A tuple of one array of samples and one integer.
+    :rtype: (array, int)
+
+    .. seealso:: :meth:`__next__`
+
+    .. rubric:: Example
+
+    >>> src = aubio.source('stereo.wav')
+    >>> while True:
+    ...     samples, read = src()
+    ...     if read < src.hop_size:
+    ...         break
+
+  .. function:: __next__()
+
+    Read at most `hop_size` new frames from self, return them in
+    an array.
+
+    If source was opened with one channel, next(self) returns
+    an array of shape `(read,)`, where `read` is the actual
+    number of frames read (`0 <= read <= hop_size`).
+
+    If `source` was opened with more then one channel, the
+    returned arrays will be of shape `(channels, read)`, where
+    `read` is the actual number of frames read (`0 <= read <=
+    hop_size`).
+
+    :return: A tuple of one array of frames and one integer.
+    :rtype: (array, int)
+
+    .. seealso:: :meth:`__call__`
+
+    .. rubric:: Example
+
+    >>> for frames in aubio.source('song.flac')
+    ...     print(samples.shape)
+
+  .. function:: __iter__()
+
+    Implement iter(self).
+
+    .. seealso:: :meth:`__next__`
+
+  .. function:: __enter__()
+
+    Implement context manager interface. The file will be opened
+    upon entering the context. See `with` statement.
+
+    .. rubric:: Example
+
+    >>> with aubio.source('loop.ogg') as src:
+    ...     src.uri, src.samplerate, src.channels
+
+  .. function:: __exit__()
+
+    Implement context manager interface. The file will be closed
+    before exiting the context. See `with` statement.
+
+    .. seealso:: :meth:`__enter__`
+
+.. py-sink.c
+   TODO: remove special-members documentation
+
+.. autoclass:: aubio.sink
+  :members:
+
+  .. function:: __call__(vec, length)
+
+    Write `length` samples from `vec`.
+
+    :param array vec: input vector to write from
+    :param int length: number of samples to write
+    :example:
+
+    >>> with aubio.sink('foo.wav') as snk:
+    ...     snk(aubio.fvec(1025), 1025)
+
Index: doc/py_spectral.rst
===================================================================
--- doc/py_spectral.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_spectral.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,34 @@
+.. currentmodule:: aubio
+.. default-domain:: py
+
+.. members of generated classes are not yet documented
+
+Spectral features
+-----------------
+
+This section contains the documentation for:
+
+- :class:`dct`
+- :class:`fft`
+- :class:`filterbank`
+- :class:`mfcc`
+- :class:`pvoc`
+- :class:`specdesc`
+- :class:`tss`
+
+.. autoclass:: dct
+
+.. autoclass:: fft
+  :members:
+
+.. autoclass:: filterbank
+  :members:
+
+.. autoclass:: mfcc
+
+.. autoclass:: pvoc
+  :members:
+
+.. autoclass:: specdesc
+
+.. autoclass:: tss
Index: doc/py_synth.rst
===================================================================
--- doc/py_synth.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_synth.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,9 @@
+.. currentmodule:: aubio
+.. default-domain:: py
+
+Synthesis
+---------
+
+.. autoclass:: sampler
+
+.. autoclass:: wavetable
Index: doc/py_temporal.rst
===================================================================
--- doc/py_temporal.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_temporal.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,8 @@
+.. currentmodule:: aubio
+.. default-domain:: py
+
+Digital filters
+---------------
+
+.. autoclass:: digital_filter
+  :members:
Index: doc/py_utils.rst
===================================================================
--- doc/py_utils.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/py_utils.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,84 @@
+.. default-domain:: py
+.. currentmodule:: aubio
+
+Utilities
+---------
+
+This section documents various helper functions included in the aubio library.
+
+Note name conversion
+....................
+
+.. midiconv.py
+
+.. autofunction:: note2midi
+
+.. autofunction:: midi2note
+
+.. autofunction:: freq2note
+
+.. autofunction:: note2freq
+
+Frequency conversion
+....................
+
+.. python/ext/ufuncs.c
+
+.. autofunction:: freqtomidi
+
+.. autofunction:: miditofreq
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: meltohz
+
+.. autofunction:: hztomel
+
+.. python/ext/aubiomodule.c
+
+.. autofunction:: bintomidi
+.. autofunction:: miditobin
+.. autofunction:: bintofreq
+.. autofunction:: freqtobin
+
+Audio file slicing
+..................
+
+.. slicing.py
+
+.. autofunction:: slice_source_at_stamps
+
+Windowing
+.........
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: window
+
+Audio level detection
+.....................
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: level_lin
+.. autofunction:: db_spl
+.. autofunction:: silence_detection
+.. autofunction:: level_detection
+
+Vector utilities
+................
+
+.. python/ext/aubiomodule.c
+
+.. autofunction:: alpha_norm
+.. autofunction:: zero_crossing_rate
+.. autofunction:: min_removal
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: shift
+.. autofunction:: ishift
+
+.. python/ext/ufuncs.c
+
+.. autofunction:: unwrap2pi
Index: doc/python.rst
===================================================================
--- doc/python.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
+++ doc/python.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -0,0 +1,59 @@
+.. make sure our default-domain is python here
+.. default-domain:: py
+
+.. set current module
+.. currentmodule:: aubio
+
+..
+   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_datatypes
+   py_io
+   py_temporal
+   py_spectral
+   py_analysis
+   py_synth
+   py_utils
+   py_examples
+
+Introduction
+------------
+
+This document provides a reference guide. For documentation on how to
+install aubio, see :ref:`python-install`.
+
+Examples included in this guide and within the code are written assuming
+both `aubio` and `numpy`_ have been imported:
+
+.. 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
Index: doc/python_module.rst
===================================================================
--- doc/python_module.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/python_module.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -1,73 +1,103 @@
-.. _python:
+.. _python-install:
 
-Python module
-=============
+Installing aubio for Python
+===========================
 
-The aubio extension for Python is available for Python 2.7 and Python 3.
+aubio is available as a package for Python 2.7 and Python 3. The aubio
+extension is written C using the `Python/C`_ and the `Numpy/C`_ APIs.
+
+.. _Python/C: https://docs.python.org/c-api/index.html
+.. _Numpy/C: https://docs.scipy.org/doc/numpy/reference/c-api.html
+
+For general documentation on how to install Python packages, see `Installing
+Packages`_.
 
 Installing aubio with pip
 -------------------------
 
-aubio can now be installed using ``pip``:
+aubio can be installed from `PyPI`_ using ``pip``:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ pip install aubio
 
-Building the module
--------------------
+See also `Installing from PyPI`_ for general documentation.
 
-From ``aubio`` source directory, run the following:
+.. note::
 
-.. code-block:: bash
+  aubio is currently a `source only`_ package, so you will need a compiler to
+  install it from `PyPI`_. See also `Installing aubio with conda`_ for
+  pre-compiled binaries.
+
+.. _PyPI: https://pypi.python.org/pypi/aubio
+.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
+.. _Installing from PyPI: https://packaging.python.org/tutorials/installing-packages/#installing-from-pypi
+.. _source only: https://packaging.python.org/tutorials/installing-packages/#source-distributions-vs-wheels
+
+Installing aubio with conda
+---------------------------
+
+`Conda packages`_ are available through the `conda-forge`_ channel for Linux,
+macOS, and Windows:
+
+.. code-block:: console
+
+    $ conda config --add channels conda-forge
+    $ conda install -c conda-forge aubio
+
+.. _Conda packages: https://anaconda.org/conda-forge/aubio
+.. _conda-forge: https://conda-forge.org/
+
+.. _py-doubleprecision:
+
+Double precision
+----------------
+
+This module can be compiled in double-precision mode, in which case the
+default type for floating-point samples will be 64-bit. The default is
+single precision mode (32-bit, recommended).
+
+To build the aubio module with double precision, use the option
+`--enable-double` of the `build_ext` subcommand:
+
+.. code:: bash
 
     $ ./setup.py clean
-    $ ./setup.py build
-    $ sudo ./setup.py install
+    $ ./setup.py build_ext --enable-double
+    $ pip install -v .
 
-Using aubio in python
----------------------
+**Note**: If linking against `libaubio`, make sure the library was also
+compiled in :ref:`doubleprecision` mode.
 
-Once you have python-aubio installed, you should be able to run ``python -c
-"import aubio; print(aubio.version)"``.
 
-A simple example
-................
+Checking your installation
+--------------------------
 
-Here is a :download:`simple script <../python/demos/demo_source_simple.py>`
-that reads all the samples from a media file:
+Once the python module is installed, its version can be checked with:
 
-.. literalinclude:: ../python/demos/demo_source_simple.py
-   :language: python
+.. code-block:: console
 
-Filtering an input sound file
-.............................
+    $ python -c "import aubio; print(aubio.version, aubio.float_type)"
 
-Here is a more complete example, :download:`demo_filter.py
-<../python/demos/demo_filter.py>`. This files executes the following:
+The command line `aubio` is also installed:
 
-* read an input media file (``aubio.source``)
+.. code-block:: console
 
-* filter it using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
-  filter (``aubio.digital_filter``)
+    $ aubio -h
 
-* 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``.
+A number of Python tests are provided in the `python/tests`_ folder. To run
+them, install `pytest`_ and run it from the aubio source directory:
 
-.. _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
+.. code-block:: console
 
+    $ pip install pytest
+    $ git clone https://git.aubio.org/aubio/aubio
+    $ cd aubio
+    $ pytest
+
+.. _python/tests: https://github.com/aubio/aubio/blob/master/python/tests
+.. _pytest: https://pytest.org
Index: doc/requirements.rst
===================================================================
--- doc/requirements.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/requirements.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -31,4 +31,7 @@
     If ``pkg-config`` is not found in ``PATH``, the configure step will
     succeed, but none of the external libraries will be used.
+
+Media libraries
+---------------
 
 libav
@@ -79,4 +82,7 @@
 configure with ``--disable-samplerate``
 
+Optimisation libraries
+----------------------
+
 libfftw3
 ........
@@ -92,4 +98,98 @@
 then fail if the required library is not found. To disable this option,
 configure with ``--disable-fftw3``
+
+blas
+....
+
+On macOs/iOS, `blas
+<https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_ are made
+available through the Accelerate framework.
+
+On Linux, they can be enabled with ``--enable-blas``.  On Debian (etch),
+`atlas`_, `openblas`_, and `libblas`_ have been successfully tested.
+
+When enabled, ``waf`` will check for the current blas configuration by running
+``pkg-config --libs blas``. Depending of the library path returned by
+``pkg-config``, different headers will be searched for.
+
+.. note::
+
+    On Debian systems, `multiple versions of BLAS and LAPACK
+    <https://wiki.debian.org/DebianScience/LinearAlgebraLibraries>`_ can be
+    installed. To configure which libblas is being used:
+
+    .. code-block:: console
+
+      $ sudo update-alternatives --config libblas.so
+
+..
+  Expected pkg-config output for each alternative:
+    /usr/lib/atlas-base/atlas/libblas.so
+    -L/usr/lib/atlas-base/atlas -lblas
+    /usr/lib/openblas-base/libblas.so
+    -L/usr/lib/openblas-base -lblas
+    /usr/lib/libblas/libblas.so
+    -lblas
+
+atlas
+.....
+
+`ATLAS BLAS APIs <http://math-atlas.sourceforge.net/>`_ will be used the path
+returned by ``pkg-config --libs blas`` contains ``atlas``.
+
+..
+  ``<atlas/cblas.h>`` will be included.
+
+Example:
+
+.. code-block:: console
+
+  $ pkg-config --libs blas
+  -L/usr/lib/atlas-base/atlas -lblas
+  $ ./waf configure --enable-atlas
+  [...]
+  Checking for 'blas'                      : yes
+  Checking for header atlas/cblas.h        : yes
+
+openblas
+........
+
+`OpenBlas libraries <https://www.openblas.net/>`_ will be used when the output
+of ``pkg-config --libs blas`` contains 'openblas',
+
+..
+  ``<openblas/cblas.h>`` will be included.
+
+Example:
+
+.. code-block:: console
+
+  $ pkg-config --libs blas
+  -L/usr/lib/openblas-base -lblas
+  $ ./waf configure --enable-atlas
+  [...]
+  Checking for 'blas'                      : yes
+  Checking for header openblas/cblas.h     : yes
+
+libblas
+.......
+
+`Netlib's libblas (LAPACK) <https://www.netlib.org/lapack/>`_ will be used if
+no specific library path is specified by ``pkg-config``
+
+..
+  ``<cblas.h>`` will be included.
+
+Example:
+
+.. code-block:: console
+
+  $ pkg-config --libs blas
+  -lblas
+  $ ./waf configure --enable-atlas
+  [...]
+  Checking for 'blas'                      : yes
+  Checking for header cblas.h              : yes
+
 
 Platform notes
@@ -198,10 +298,41 @@
                 uninstall clean distclean dist distcheck
 
+.. _doubleprecision:
+
 Double precision
 ................
 
+The datatype used to store real numbers in aubio is named `smpl_t`. By default,
+`smpl_t` is defined as `float`, a `single-precision format
+<https://en.wikipedia.org/wiki/Single-precision_floating-point_format>`_
+(32-bit).  Some algorithms require a floating point representation with a
+higher precision, for instance to prevent arithmetic underflow in recursive
+filters.  In aubio, these special samples are named `lsmp_t` and defined as
+`double` by default (64-bit).
+
+Sometimes it may be useful to compile aubio in `double-precision`, for instance
+to reproduce numerical results obtained with 64-bit routines. In this case,
+`smpl_t` will be defined as `double`.
+
+The following table shows how `smpl_t` and `lsmp_t` are defined in single- and
+double-precision modes:
+
+.. list-table:: Single and double-precision modes
+   :align: center
+
+   * -
+     - single
+     - double
+   * - `smpl_t`
+     - ``float``
+     - ``double``
+   * - `lsmp_t`
+     - ``double``
+     - ``long double``
+
 To compile aubio in double precision mode, configure with ``--enable-double``.
 
-To compile aubio in single precision mode, use ``--disable-double`` (default).
+To compile in single-precision mode (default), use ``--disable-double`` (or
+simply none of these two options).
 
 Disabling the tests
Index: doc/statuslinks.rst
===================================================================
--- doc/statuslinks.rst	(revision 086a45b7640bf382a41603abcf3b23ac36d5067a)
+++ doc/statuslinks.rst	(revision f2f1b10093db6eff9ce2d3d108b41d94e04c0e6e)
@@ -10,13 +10,9 @@
    :alt: Appveyor build status
 
-.. image:: https://landscape.io/github/aubio/aubio/master/landscape.svg?style=flat
-   :target: https://landscape.io/github/aubio/aubio/master
-   :alt: Landscape code health
-
 .. image:: https://readthedocs.org/projects/aubio/badge/?version=latest
    :target: https://aubio.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation status
 
-.. image:: https://img.shields.io/github/commits-since/aubio/aubio/0.4.6.svg?maxAge=2592000
+.. image:: https://img.shields.io/github/commits-since/aubio/aubio/latest.svg
    :target: https://github.com/aubio/aubio
    :alt: Commits since last release
