removed obsolete stuff; added acks

docs/development.rst

@@ -42,6 +42,8 @@ and/or guide you through the implementation.
 Alternatively, you can look for anything tagged with "feature request" or
 "enhancement" on the `issue tracker on GitHub`_.
 
+.. _write_documentation:
+
 Write documentation
 ~~~~~~~~~~~~~~~~~~~
 
@@ -60,7 +62,7 @@ As a very easy way of just fixing issues in the documentation, use the *Edit
 on GitHub* link on the top right of a documentation page or the *[source]* link
 of an entity in the API reference to open the corresponding source file in
 GitHub, then click the *Edit this file* link to edit the file in your browser
-and send us a Pull Request. All you need for this is a free GitHub account.
+and send us a Pull Request.
 
 For any more substantial changes, please follow the steps below.
 
@@ -78,9 +80,7 @@ Documentation
 
 The documentation is generated with `Sphinx
 <http://sphinx-doc.org/latest/index.html>`_. To build it locally, run the
-following commands:
-
-.. code:: bash
+following commands::
 
     cd docs
     make html

docs/index.rst

@@ -8,36 +8,34 @@ It's main features / design goals are:
 
 * ease of use,
 * rapid prototyping of signal processing workflows,
-* most stuff is modeled as numpy arrays (enhanced by additional methods and
+* most things are modeled as numpy arrays (enhanced by additional methods and
   attributes),
 * simple conversion to a running program by the use of processors.
 
 Madmom is a work in progress, input is always welcome. The available
-documentation is limited for now, but
-:doc:`you can help to improve it </development>`.
+documentation is limited for now, but :ref:`you can help to improve it
+<write_documentation>`.
 
-User Guide
-----------
+The documentation is split into several parts:
 
-The madmom user guide explains how to install madmom, how to get things done
-and how to contribute to the library as a developer.
+* The :ref:`user_guide` explains how to install, use and conrtibute to madmom.
+* If you are looking for information on a specific function, class or method,
+  the :ref:`api_reference` is for you.
+
+.. _user_guide:
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
+  :caption: User Guide
 
   installation
-  tutorial
   development
 
-
-API Reference
--------------
-
-If you are looking for information on a specific function, class or method,
-this part of the documentation is for you.
+.. _api_reference:
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 3
+  :caption: API Reference
 
   modules/audio
   modules/features
@@ -53,4 +51,13 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+Acknowledgements
+----------------
+
+Supported by the European Commission through the `GiantSteps project
+<http://www.giantsteps-project.eu>`_ (FP7 grant agreement no. 610591) and the
+`Phenicx project <http://phenicx.upf.edu>`_ (FP7 grant agreement no. 601166)
+as well as the `Austrian Science Fund (FWF) <https://www.fwf.ac.at>`_ project
+Z159.
+
 .. _GitHub: https://github.com/CPJKU/madmom

docs/installation.rst

@@ -20,6 +20,8 @@ Please refer to the ``requirements.txt`` file for the minimum required versions
 and make sure that these modules are up to date, otherwise it can result in
 unexpected errors or false computations!
 
+.. _install_from_package:
+
 Install from package
 --------------------
 
@@ -30,7 +32,7 @@ The instructions given here should be used if you just want to install the
 package (e.g. to run the bundled programs).
 
 The easiest way to install the package is via ``pip`` from the `PyPI (Python
-Package Index) <https://pypi.python.org/pypi>`_:
+Package Index) <https://pypi.python.org/pypi>`_::
 
     pip install madmom
 
@@ -41,7 +43,7 @@ already. ``pip`` will output the install location.
 
 You might need higher privileges (use su or sudo) to install the package, model
 files and scripts globally. Alternatively you can install the package locally
-(i.e. only for you) by adding the ``--user`` argument:
+(i.e. only for you) by adding the ``--user`` argument::
 
     pip install --user madmom
 
@@ -57,82 +59,50 @@ directly or add their path to your ``$PATH`` environment variable:
 Install from source
 -------------------
 
-If you plan to use the package as a developer, clone the Git repository:
+If you plan to use the package as a developer, clone the Git repository::
 
     git clone https://github.com/CPJKU/madmom.git
 
 Since the pre-trained model/data files are not included in this repository but
-rather added as a Git submodule, you either have to clone the repo recursively:
+rather added as a Git submodule, you either have to clone the repo
+recursively::
 
     git clone --recursive https://github.com/CPJKU/madmom.git
 
-or init the submodule and fetch the data manually:
+or init the submodule and fetch the data manually::
 
     cd /path/to/madmom
-
     git submodule update --init --remote
 
 You can then either include the package directory in your ``$PYTHONPATH``, or
-you can simply install the package in development mode:
+you can simply install the package in development mode::
 
     python setup.py develop --user
 
 If you change any ``.pyx`` or ``.pxd`` files, you have to (re-)compile the
-modules with Cython. To do so, please run the above command again or:
+modules with Cython. To do so, please run the above command again or::
 
     python setup.py build_ext --inplace
 
-To run the included tests:
+To run the included tests::
 
     python setup.py test
 
-Package structure
------------------
-
-The package has a very simple structure, divided into the following folders:
-
-`/bin <bin>`_
-  example programs (i.e. executable algorithms)
-`/docs <docs>`_
-  sphinx documentation of the package
-`/madmom <madmom>`_
-  the package itself
-`/madmom/audio <madmom/audio>`_
-  low level features (e.g. audio file handling, STFT)
-`/madmom/evaluation <madmom/evaluation>`_
-  evaluation code
-`/madmom/features <madmom/features>`_
-  higher level features (e.g. onsets, beats)
-`/madmom/ml <madmom/ml>`_
-  machine learning stuff (e.g. RNNs, HMMs)
-`/madmom/models <madmom/models>`_
-  pre-trained model/data files (please note the license)
-`/madmom/utils <madmom/utils>`_
-  misc stuff (e.g. MIDI and general file handling)
-`/tests <tests>`_
-  tests
-
-Almost all low level features (i.e. everything under
-`/madmom/audio <madmom/audio>`_) are divided into a data class and a
-corresponding processor class. The data class refers always to a certain
-instance (e.g. the STFT of an audio file), whereas the processor classes are
-used to define processing chains through which the audio is processed (i.e.
-most stuff in `/madmom/features <madmom/features>`_).
-
 Executable programs
 -------------------
 
-The package includes executable programs in the `/bin <bin>`_ folder. These are
-usually standalone reference implementations of the algorithms contained in the
-package.
+The package includes executable programs in the ``/bin`` folder. These are
+standalone reference implementations of the algorithms contained in the
+package. If you just want to try/use these programs, please follow the
+:ref:`instruction to install from a package <install_from_package>`.
 
 All scripts can be run in different modes: in ``single`` file mode to process
-a single audio file and write the output to STDOUT or the given output file.
+a single audio file and write the output to STDOUT or the given output file::
 
     SuperFlux single [-o OUTFILE] INFILE
 
 If multiple audio files should be processed, the scripts can also be run in
-``batch`` mode to write the outputs to files with the given suffix.
+``batch`` mode to write the outputs to files with the given suffix::
 
     SuperFlux batch [--o OUTPUT_DIR] [-s OUTPUT_SUFFIX] LIST OF INPUT FILES
 
@@ -141,11 +111,3 @@ location as the audio files.
 
 The ``pickle`` mode can be used to store the used parameters to be able to
 exactly reproduce experiments.
-
-Note
-----
-
-The features are considered work in progress and thus can change without prior
-notice, especially the default values can be updated from time to time if they
-are more sensible than the previous ones. If your program relies on certain
-values, please make sure that you set them explicitely!