Changeset e893e6fe for doc

Timestamp:

Nov 22, 2018, 6:41:41 PM (5 years ago)

Author:

Paul Brossier <piem@piem.org>

Branches:

feature/autosink, feature/cnn, feature/cnn_org, feature/constantq, feature/crepe, feature/crepe_org, feature/pitchshift, feature/timestretch, fix/ffmpeg5, master

Children:

263dd04

Parents:

bf3f09b (diff), c4a8bc1 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'master' into feature/pytest

Location:

doc

Files:

• aubiocut.txt (modified) (1 diff)
• python_module.rst (modified) (3 diffs)
• requirements.rst (modified) (1 diff)

doc/aubiocut.txt

@@ -51 +51 @@
   each slice (default 0).
 
+  --create-first  Alway create first slice.
+
   -h, --help  Print a short help message and exit.
 

doc/python_module.rst

@@ -4 +4 @@
 ===========================
 
-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:: console
@@ -15 +22 @@
     $ pip install aubio
 
-Building the module
--------------------
+See also `Installing from PyPI`_ for general documentation.
 
-From ``aubio`` source directory, run the following:
+.. note::
+
+  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
 
-    $ ./setup.py clean
-    $ ./setup.py build
-    $ sudo ./setup.py install
+    $ 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:
@@ -68 +90 @@
 ------------
 
-A number of python tests are provided. To run them, use [pytest] from the
-aubio source tree:
+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:
 
+.. code-block:: console
+
+    $ pip install pytest
+    $ git clone https://git.aubio.org/aubio/aubio
     $ cd aubio
     $ pytest
 
-Each test script can also be called individually. For instance:
-
-    $ ./python/tests/test_note2midi.py -v
-
-[pytest]: https://pytest.org
+.. _python/tests: https://github.com/aubio/aubio/blob/master/python/tests
+.. _pytest: https://pytest.org

doc/requirements.rst

@@ -303 +303 @@
 ................
 
+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,
-recommended).
+To compile in single-precision mode (default), use ``--disable-double`` (or
+simply none of these two options).
 
 Disabling the tests