From 7a8a07e25b5165e90b1690856ff8a7464e9f0595 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Sat, 27 Aug 2016 17:23:58 +0200
Subject: [PATCH] doc/develop.rst: add some documentation about the c-api

---
 doc/develop.rst      | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst        |   5 +--
 doc/requirements.rst |   4 +--
 3 files changed, 105 insertions(+), 4 deletions(-)
 create mode 100644 doc/develop.rst

diff --git a/doc/develop.rst b/doc/develop.rst
new file mode 100644
index 00000000..7366e644
--- /dev/null
+++ b/doc/develop.rst
@@ -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!
+
diff --git a/doc/index.rst b/doc/index.rst
index 9cf59bbb..3f17e520 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -39,6 +39,7 @@ Content
    installing
    cli
    python_module
+   develop
 
 Project pages
 =============
@@ -46,13 +47,13 @@ Project pages
 * `Project homepage`_: https://aubio.org
 * `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
 
 .. _Project homepage: https://aubio.org
 .. _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/
 
 Current status
diff --git a/doc/requirements.rst b/doc/requirements.rst
index 876765ea..b0e71c6b 100644
--- a/doc/requirements.rst
+++ b/doc/requirements.rst
@@ -174,7 +174,7 @@ 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
+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.
 
@@ -187,7 +187,7 @@ External tools
 
 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`
 
 These tools are searched for in the current ``PATH`` environment variable.
-- 
2.11.0