ref: 7a8a07e25b5165e90b1690856ff8a7464e9f0595
parent: 3438b42b5bad9199d5672a5d1f0e5f21812278d7
author: Paul Brossier <piem@piem.org>
date: Sat Aug 27 13:23:58 EDT 2016
doc/develop.rst: add some documentation about the c-api
--- /dev/null
+++ b/doc/develop.rst
@@ -1,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!
+
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -39,6 +39,7 @@
installing
cli
python_module
+ develop
Project pages
=============
@@ -46,13 +47,13 @@
* `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
--- a/doc/requirements.rst
+++ b/doc/requirements.rst
@@ -174,7 +174,7 @@
`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 @@
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.