Index: doc/develop.rst
===================================================================
--- doc/develop.rst	(revision 7a8a07e25b5165e90b1690856ff8a7464e9f0595)
+++ doc/develop.rst	(revision 7a8a07e25b5165e90b1690856ff8a7464e9f0595)
@@ -0,0 +1,100 @@
+Developping with aubio
+======================
+
+Read `Contribute`_ to report issues and request new features.
+
+See `Doxygen documentation`_ for the complete documentation of the C library,
+built using `Doxygen <http://www.doxygen.org/>`_.
+
+Below is a brief `Library overview`_.
+
+Library overview
+----------------
+
+Here is a brief overview of the C library. See also the `Doxygen
+documentation`_ for a more detailed list of available functions.
+
+Vectors and matrix
+``````````````````
+
+``fvec_t`` are used to hold vectors of float (``smpl_t``).
+
+.. literalinclude:: ../tests/src/test-fvec.c
+   :language: C
+   :lines: 7
+
+
+.. code-block:: C
+
+        // set some elements
+        vec->data[511] = 2.;
+        vec->data[vec->length-2] = 1.;
+
+Similarly, ``fmat_t`` are used to hold matrix of floats.
+
+.. literalinclude:: ../tests/src/test-fmat.c
+   :language: C
+   :lines: 9-19
+
+Reading a sound file
+````````````````````
+In this example, ``aubio_source`` is used to read a media file.
+
+First, create the objects we need.
+
+.. literalinclude:: ../tests/src/io/test-source.c
+   :language: C
+   :lines: 22-24, 30-32, 34
+
+.. note::
+   With ``samplerate = 0``, ``aubio_source`` will be created with the file's
+   original samplerate.
+
+Now for the processing loop:
+
+.. literalinclude:: ../tests/src/io/test-source.c
+   :language: C
+   :lines: 40-44
+
+At the end of the processing loop, clean-up and de-allocate memory:
+
+.. literalinclude:: ../tests/src/io/test-source.c
+   :language: C
+   :lines: 50-56
+
+See the complete example: :download:`test-source.c
+<../tests/src/io/test-source.c>`.
+
+Computing the spectrum
+``````````````````````
+
+Now let's create a phase vocoder:
+
+.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
+   :language: C
+   :lines: 6-11
+
+The processing loop could know look like:
+
+.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
+   :language: C
+   :lines: 21-35
+
+See the complete example: :download:`test-phasevoc.c
+<../tests/src/spectral/test-phasevoc.c>`.
+
+.. _doxygen-documentation:
+
+Doxygen documentation
+---------------------
+
+The latest version of the doxygen documentation is available at:
+
+    https://aubio.org/doc/latest
+
+Contribute
+----------
+
+Please report any issue and feature request at the `Github issue tracker
+<https://github.com/aubio/aubio/issues>`_. Patches and pull-requests welcome!
+
Index: doc/index.rst
===================================================================
--- doc/index.rst	(revision 3438b42b5bad9199d5672a5d1f0e5f21812278d7)
+++ doc/index.rst	(revision 7a8a07e25b5165e90b1690856ff8a7464e9f0595)
@@ -40,4 +40,5 @@
    cli
    python_module
+   develop
 
 Project pages
@@ -47,5 +48,5 @@
 * `aubio on github`_: https://github.com/aubio/aubio
 * `aubio on pypi`_: https://pypi.python.org/pypi/aubio
-* `API documentation`_: https://aubio.org/doc/latest/
+* `Doxygen documentation`_: https://aubio.org/doc/latest/
 * `Mailing lists`_: https://lists.aubio.org
 
@@ -53,5 +54,5 @@
 .. _aubio on github: https://github.com/aubio/aubio
 .. _aubio on pypi: https://pypi.python.org/pypi/aubio
-.. _api documentation: https://aubio.org/doc/latest/
+.. _Doxygen documentation: https://aubio.org/doc/latest/
 .. _Mailing lists: https://lists.aubio.org/
 
Index: doc/requirements.rst
===================================================================
--- doc/requirements.rst	(revision 3438b42b5bad9199d5672a5d1f0e5f21812278d7)
+++ doc/requirements.rst	(revision 7a8a07e25b5165e90b1690856ff8a7464e9f0595)
@@ -175,5 +175,5 @@
   transform
 
-With libfftw3 built in, ``aubio_fft`` will use `FFTW <http://fftw.org>`_ to
+With libfftw3 built in, ``aubio_fft`` will use `FFTW`_ to
 compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length
 that are not a power of 2.
@@ -188,5 +188,5 @@
 If the following tools are found, additional documentations are built:
 
- - `doxygen <http://doxygen.org>`_ to build the `API documentation`.
+ - `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
  - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
 
