Index: doc/building.rst
===================================================================
--- doc/building.rst	(revision 5069da371ee058f9658a7cb8e72909d97d6899b2)
+++ doc/building.rst	(revision 5069da371ee058f9658a7cb8e72909d97d6899b2)
@@ -0,0 +1,98 @@
+.. highlight:: bash
+
+.. _building:
+
+Building aubio
+==============
+
+.. note::
+    To download a prebuilt version of aubio, see :ref:`download`.
+
+aubio uses `waf`_ to configure, compile, and test the source.
+A copy of waf is included in aubio tarball, so all you need is a terminal,
+a compiler, and a recent version of python installed.
+
+.. note::
+    Make sure you have all the :ref:`requirements` you want before building.
+
+Latest release
+--------------
+
+The **latest stable release** can be downloaded from https://aubio.org/download::
+
+        $ curl -O http://aubio.org/pub/aubio-0.4.3.tar.bz2
+        $ tar xf aubio-0.4.3.tar.bz2
+        $ cd aubio-0.4.3
+
+Git repository
+--------------
+
+The **latest git branch** can be obtained with::
+
+        $ git clone git://git.aubio.org/git/aubio
+        $ cd aubio
+
+The following command will fetch the correct `waf`_ version (not included in
+aubio's git)::
+
+        $ ./scripts/get_waf.sh
+
+.. note::
+
+  Windows users without `Git Bash`_ installed will want to use the following
+  commands instead:
+
+  .. code:: bash
+
+        $ curl -fsS -o waf https://waf.io/waf-1.8.22
+        $ curl -fsS -o waf.bat https://raw.githubusercontent.com/waf-project/waf/master/utils/waf.bat
+
+
+Compiling
+---------
+
+To compile the C library, examples programs, and tests, run::
+
+        $ ./waf configure
+
+Check out the available options using ``./waf configure --help``. Once
+you are done with configuration, you can start building::
+
+        $ ./waf build
+
+To install the freshly built C library and tools, simply run the following
+command::
+
+        $ sudo ./waf install
+
+.. note::
+  Windows users should simply run ``waf``, without the leading ``./``. For
+  instance:
+
+  .. code:: bash
+
+       $ waf configure build
+
+Cleaning
+--------
+
+If you wish to uninstall the files installed by the ``install`` command, use
+``uninstall``::
+
+        $ sudo ./waf uninstall
+
+To clean the source directory, use the ``clean`` command::
+
+        $ ./waf clean
+
+To also forget the options previously passed to the last ``./waf configure``
+invocation, use the ``distclean`` command::
+
+        $ ./waf distclean
+
+.. _waf: https://waf.io/
+
+.. _Git Bash: https://git-for-windows.github.io/
+
+.. toctree::
+   :maxdepth: 2
Index: doc/download.rst
===================================================================
--- doc/download.rst	(revision 88f7cf9218348b6d14a2421cceb680801eda0fa5)
+++ doc/download.rst	(revision 5069da371ee058f9658a7cb8e72909d97d6899b2)
@@ -3,6 +3,4 @@
 Downloading aubio
 =================
-
-aubio runs on Linux, Windows, macOS, iOS, Android, and most operating systems.
 
 A number of distributions already include aubio. Check your favorite package
@@ -19,2 +17,4 @@
   xcode_frameworks
   android
+
+To compile aubio from source, read :ref:`building`.
Index: doc/installing.rst
===================================================================
--- doc/installing.rst	(revision 88f7cf9218348b6d14a2421cceb680801eda0fa5)
+++ doc/installing.rst	(revision 5069da371ee058f9658a7cb8e72909d97d6899b2)
@@ -1,93 +1,19 @@
-.. highlight:: bash
+Installing aubio
+================
 
-Building aubio
-==============
+aubio runs on Linux, Windows, macOS, iOS, Android, and probably quite a few
+others operating systems.
 
-.. note::
-    To download a prebuilt version of aubio, see :ref:`download`.
+To download a pre-compiled version of the library, head to :ref:`download`.
 
-aubio uses `waf`_ to configure, compile, and test the source.
-A copy of waf is included in aubio tarball, so all you need is a terminal,
-a compiler, and a recent version of python installed.
+To install the python extension, head to :ref:`python`.
 
-Latest release
---------------
-
-The **latest stable release** can be downloaded from https://aubio.org/download::
-
-        $ curl -O http://aubio.org/pub/aubio-0.4.3.tar.bz2
-        $ tar xf aubio-0.4.3.tar.bz2
-        $ cd aubio-0.4.3
-
-Git repository
---------------
-
-The **latest git branch** can be obtained with::
-
-        $ git clone git://git.aubio.org/git/aubio
-        $ cd aubio
-
-The following command will fetch the correct `waf`_ version (not included in
-aubio's git)::
-
-        $ ./scripts/get_waf.sh
-
-.. note::
-
-  Windows users without `Git Bash`_ installed will want to use the following
-  commands instead:
-
-  .. code:: bash
-
-        $ curl -fsS -o waf https://waf.io/waf-1.8.22
-        $ curl -fsS -o waf.bat https://raw.githubusercontent.com/waf-project/waf/master/utils/waf.bat
-
-
-Compiling
----------
-
-To compile the C library, examples programs, and tests, run::
-
-        $ ./waf configure
-
-Check out the available options using ``./waf configure --help``. Once
-you are done with configuration, you can start building::
-
-        $ ./waf build
-
-To install the freshly built C library and tools, simply run the following
-command::
-
-        $ sudo ./waf install
-
-.. note::
-  Windows users should simply run ``waf``, without the leading ``./``. For
-  instance:
-
-  .. code:: bash
-
-       $ waf configure build
-
-Cleaning
---------
-
-If you wish to uninstall the files installed by the ``install`` command, use
-``uninstall``::
-
-        $ sudo ./waf uninstall
-
-To clean the source directory, use the ``clean`` command::
-
-        $ ./waf clean
-
-To also forget the options previously passed to the last ``./waf configure``
-invocation, use the ``distclean`` command::
-
-        $ ./waf distclean
-
-.. _waf: https://waf.io/
-
-.. _Git Bash: https://git-for-windows.github.io/
+To compile aubio form source, first check the :ref:`requirements`, then read
+:ref:`building`.
 
 .. toctree::
    :maxdepth: 2
+
+   download
+   requirements
+   building
Index: doc/requirements.rst
===================================================================
--- doc/requirements.rst	(revision 5069da371ee058f9658a7cb8e72909d97d6899b2)
+++ doc/requirements.rst	(revision 5069da371ee058f9658a7cb8e72909d97d6899b2)
@@ -0,0 +1,178 @@
+.. _requirements:
+
+Requirements
+============
+
+While aubio should build without any additional external libraries, we
+**strongly recommend** to build aubio with some additional dependancies.
+
+Platform notes
+--------------
+
+Linux
+.....
+
+The following `External libraries`_ will be used if found: `libav`_,
+`libsamplerate`_, `libsndfile`_, `libfftw3`_.
+
+macOS
+.....
+
+The following system frameworks will be used on Mac OS X systems:
+
+  - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
+    FFTs and other vectorized operations optimally.
+
+  - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
+    `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
+    decode audio from files and network streams.
+
+.. note::
+
+  To build a fat binary for both ``i386`` and ``x86_64``, use ``./waf configure
+  --enable-fat``.
+
+The following `External libraries`_ will also be checked: `libav`_,
+`libsamplerate`_, `libsndfile`_, `libfftw3`_.
+
+Windows
+.......
+
+The following `External libraries`_ will be used if found: `libav`_,
+`libsamplerate`_, `libsndfile`_, `libfftw3`_.
+
+iOS
+...
+
+The following system frameworks will be used on iOS and iOS Simulator.
+
+  - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
+    FFTs and other vectorized operations optimally.
+
+  - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
+    `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
+    decode audio from files and network streams.
+
+To build aubio for iOS, configure with ``--with-target-platform=ios``. For the
+iOS Simulator, use ``--with-target-platform=iosimulator`` instead.
+
+By default, aubio is built with the following flags on iOS:
+
+.. code:: bash
+
+    CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"
+
+and on iOS Simulator:
+
+.. code::
+
+    CFLAGS="-fembed-bitcode -arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
+
+Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
+``wscript`` directly.
+
+Build options
+-------------
+
+These options can be passed to configure
+
+Double precision
+................
+
+To compile aubio in double precision mode, configure with ``--enable-double``.
+
+To compile aubio in single precision mode, use ``--disable-double`` (default).
+
+Fat binary
+..........
+
+To build a fat binary on Mac OS platforms, configure with ``--enable-fat``.
+
+External libraries
+------------------
+
+External libraries are checked for using ``pkg-config``. Set the
+``PKG_CONFIG_PATH`` environment variable if you have them installed in an
+unusual location.
+
+
+.. note::
+
+    If ``pkg-config`` is not found in ``PATH``, the configure step will
+    succeed, but none of the external libraries will be used.
+
+libav
+.....
+
+  `libav.org <https://libav.org/>`_, open source audio and video processing
+  tools.
+
+If all of the following libraries are found, they will be used to compile
+``aubio_source_avcodec``. so that ``aubio_source`` will be able to decode audio
+from all formats supported by `libav
+<https://libav.org/documentation/general.html#Audio-Codecs>`_.
+
+* libavcodec
+* libavformat
+* libavutil
+* libavresample
+
+To enable this option, configure with ``--enable-avcodec``. The build will then
+failed if the required libraries are not found. To disable this option,
+configure with ``--disable-avcodec``
+
+
+libsndfile
+..........
+
+  `libsndfile <http://www.mega-nerd.com/libsndfile/>`_, a C library for reading
+  and writing sampled sound files.
+
+With libsndfile built in, ``aubio_source_sndfile`` will be built in and used by
+``aubio_source``.
+
+To enable this option, configure with ``--enable-sndfile``. The build will then
+failed if the required library is not found. To disable this option, configure
+with ``--disable-sndfile``
+
+libsamplerate
+.............
+
+  `libsamplerate <http://www.mega-nerd.com/SRC/>`_, a sample rate converter for
+  audio.
+
+With libsamplerate built in, ``aubio_source_sndfile`` will support resampling,
+and ``aubio_resample`` will be fully functional.
+
+To enable this option, configure with ``--enable-samplerate``. The build will
+then failed if the required library is not found. To disable this option,
+configure with ``--disable-samplerate``
+
+libfftw3
+........
+
+  `FFTW <http://fftw.org/>`_, a C subroutine for computing the discrete Fourier
+  transform
+
+With libfftw3 built in, ``aubio_fft`` will use `FFTW <http://fftw.org>`_ to
+compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length
+that are not a power of 2.
+
+To enable this option, configure with ``--enable-fftw3``. The build will
+then failed if the required library is not found. To disable this option,
+configure with ``--disable-fftw3``
+
+External tools
+--------------
+
+If the following tools are found, additional documentations are built:
+
+ - `doxygen <http://doxygen.org>`_ to build the `API documentation`.
+ - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
+
+These tools are searched for in the current ``PATH`` environment variable.
+By default, the documentation is built only if the tools are found.
+
+To disable the documentation, configure with ``--disable-docs``. To build with
+the documentation, configure with ``--enable-docs``.
+
