New README and documentation strategy; changed purpose 'enrol' to 'enroll'

.gitignore

 *~
 *.swp
 *.pyc
-.DS_Store
-logs
-replay
-*.db
-.installed.cfg
-parts
-develop-eggs
+*.so
+*.dylib
 bin
 eggs
-downloads
-lib
-src
-sphinx
-.project
-.pydevproject
-.settings
-*.egg-info
+parts
+.installed.cfg
 .mr.developer.cfg
-
+*.egg-info
+develop-eggs
+sphinx
+dist
+.nfs*
+.gdb_history
+build
+*.egg
+src/

.travis.yml

@@ -6,6 +6,7 @@ matrix:
     env:
     - secure: HYFSm84gCi+EnE3hDeRfPFojhfPx7RS7xfP2cYs+tzOvE2DdL62D4ZA/bnBTCbIl4FyOKxS/3biLYu40d8UIjDYvMgx8xaT/byJB6iw4my9vnzkFl2NcbBNQA0NvoU8lBrS/zXrbz3U/JMLNDXlGDFx/GTMmvAYt2Hrttq9kxD4=
     - secure: Yfaf3JfZ7QWuEqOmExFD81KD0SDiAIB84x122zCYpcHCyqqAjWQw2v7+YBBR3F3m0sdMhrVuj/gBkmccEU/M3KLYR8jm9DiPfeenW2mdJwUBdcmM+9DCeYtnkZx8DYo3Uxpxi0WkvXmED6l6mkWHyPVSi3que9h1t3aOv/zt+2I=
+    - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
   - python: 3.2
     env:
     - NUMPYSPEC===1.8.0
@@ -15,11 +16,11 @@ matrix:
 before_install:
 - sudo add-apt-repository -y ppa:biometrics/bob
 - sudo apt-get update -qq
-- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev libatlas-dev libatlas-base-dev liblapack-dev
+- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev libatlas-dev libatlas-base-dev liblapack-dev texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
 - if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq gfortran; fi
 - if [ -n "${NUMPYSPEC}" ]; then pip install --upgrade pip setuptools; fi
 - if [ -n "${NUMPYSPEC}" ]; then pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel numpy$NUMPYSPEC; fi
-- pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel matplotlib==1.3.0 sphinx nose==1.3.0 jinja2==2.6 coveralls
+- pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel matplotlib==1.3.0 sphinx nose==1.3.0 jinja2==2.6 coveralls setuptools==7.0
 install:
 - python bootstrap.py
 - ./bin/buildout

README.rst

@@ -2,86 +2,53 @@
 .. Manuel Guenther <manuel.guenther@idiap.ch>
 .. Thu Sep  4 11:35:05 CEST 2014
 
+.. image:: http://img.shields.io/badge/docs-stable-yellow.png
+   :target: http://pythonhosted.org/bob.db.voxforge/index.html
+.. image:: http://img.shields.io/badge/docs-latest-orange.png
+   :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.voxforge/master/index.html
 .. image:: https://travis-ci.org/bioidiap/bob.db.voxforge.svg?branch=master
    :target: https://travis-ci.org/bioidiap/bob.db.voxforge
 .. image:: https://coveralls.io/repos/bioidiap/bob.db.voxforge/badge.png
    :target: https://coveralls.io/r/bioidiap/bob.db.voxforge
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.db.voxforge.png
-   :target: https://github.com/bioidiap/bob.db.voxforge
+.. image:: https://img.shields.io/badge/github-master-0000c0.png
+   :target: https://github.com/bioidiap/bob.db.voxforge/tree/master
 .. image:: http://img.shields.io/pypi/v/bob.db.voxforge.png
    :target: https://pypi.python.org/pypi/bob.db.voxforge
 .. image:: http://img.shields.io/pypi/dm/bob.db.voxforge.png
    :target: https://pypi.python.org/pypi/bob.db.voxforge
+.. image:: https://img.shields.io/badge/original-data--files-a000a0.png
+   :target: http://www.repository.voxforge1.org/downloads/SpeechCorpus/Trunk/Audio/Main/16kHz_16bit
 
+=========================================
+ Voxforge Toy Database Interface for Bob
+=========================================
 
-=======================================================
- Speaker recognition protocol on the Voxforge Database
-=======================================================
-
-`Voxforge`_ offers a collection transcribed speech for use with **Free** and **Open Source Speech Recognition Engines**.
+Voxforge_ offers a collection of transcribed speech for use with **Free** and **Open Source Speech Recognition Engines**.
 In this package, we design a speaker recognition protocol that uses a **small subset of the english audio files** (only 6561 files) belonging to **30 speakers** randomly selected.
-This subset is split into three equivalent parts: Training (10 speakers), Development (10 speakers) and Test (10 speakers) sets.
-
-This package serves as a toy example of speaker recognition database while testing `xbob.spkrec`_.
-
-The `xbob.spkrec`_  is developed at Idiap during its participation to the `NIST SRE 2012 evaluation`_. If you use this package and/or its results, please cite the following
-publications:
-
-1. The original paper presented at the NIST SRE 2012 workshop::
-
-     @inproceedings{Khoury_NISTSRE_2012,
-       author = {Khoury, Elie and El Shafey, Laurent and Marcel, S{\'{e}}bastien},
-       month = {dec},
-       title = {The Idiap Speaker Recognition Evaluation System at NIST SRE 2012},
-       booktitle = {NIST Speaker Recognition Conference},
-       year = {2012},
-       location = {Orlando, USA},
-       organization = {NIST},
-       pdf = {http://publications.idiap.ch/downloads/papers/2012/Khoury_NISTSRE_2012.pdf}
-    }
-
-2. Bob as the core framework used to run the experiments::
-
-    @inproceedings{Anjos_ACMMM_2012,
-      author = {A. Anjos and L. El Shafey and R. Wallace and M. G\"unther and C. McCool and S. Marcel},
-      title = {Bob: a free signal processing and machine learning toolbox for researchers},
-      year = {2012},
-      month = oct,
-      booktitle = {20th ACM Conference on Multimedia Systems (ACMMM), Nara, Japan},
-      publisher = {ACM Press},
-      url = {http://publications.idiap.ch/downloads/papers/2012/Anjos_Bob_ACMMM12.pdf},
-    }
-
+This subset is split into three equivalent parts: Training (10 speakers), Development (10 speakers) and Evaluation (10 speakers) sets.
 
 
 Installation
 ------------
+To install this package -- alone or together with other `Packages of Bob <https://github.com/idiap/bob/wiki/Packages>`_ -- please read the `Installation Instructions <https://github.com/idiap/bob/wiki/Installation>`_.
+For Bob_ to be able to work properly, some dependent packages are required to be installed.
+Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
 
-Just download this package and decompress it locally::
-
-  $ wget http://pypi.python.org/packages/source/x/xbob.db.voxforge/xbob.db.voxforge-0.0.1a2.zip
-  $ unzip xbob.db.voxforge-0.0.1a2.zip
-  $ cd xbob.db.voxforge-0.0.1a2
 
-Use buildout to bootstrap and have a working environment ready for
-experiments::
-
-  $ python bootstrap
-  $ ./bin/buildout
+Getting the data
+----------------
+The data can be downloaded from its original URL (on Voxforge), or by running ``./scripts/download_and_untar.sh``, which takes as input the path in which the data will be stored::
 
-This also requires that bob (>= 1.2.0) is installed.
+  $ ./scripts/download_and_untar.sh PATH/TO/WAV/DIRECTORY
 
 
-Getting the data
-~~~~~~~~~~~~~~~~
+Documentation
+-------------
+For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.db.voxforge/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.voxforge/master/index.html>`_ of the documentation.
+For a list of tutorials on this or the other packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
 
-The data can be downloaded from its original URL (on Voxforge) and extracted by running `download_and_untar.sh`_ that takes as input the path in which the data will be stored::
 
-  $ ./download_and_untar.sh PATH/TO/WAV/DIRECTORY
+.. _bob: https://www.idiap.ch/software/bob
+.. _voxforge: http://www.voxforge.org
 
-.. _Voxforge: http://www.voxforge.org/
-.. _xbob.spkrec: https://github.com/bioidiap/xbob.spkrec
-.. _NIST SRE 2012 evaluation: http://www.nist.gov/itl/iad/mig/sre12.cfm
-.. _download_and_untar.sh: https://github.com/bioidiap/xbob.db.voxforge/blob/master/download_and_untar.sh
 
-In case you need a help, please contact us.

bob/db/voxforge/driver.py

@@ -102,7 +102,7 @@ class Interface(BaseInterface):
     parser = subparsers.add_parser('dumplist', help=dumplist.__doc__)
     parser.add_argument('-d', '--directory', default='', help="if given, this path will be prepended to every entry returned.")
     parser.add_argument('-e', '--extension', default='', help="if given, this extension will be appended to every entry returned.")
-    parser.add_argument('-u', '--purpose', help="if given, this value will limit the output files to those designed for the given purposes.", choices=('enrol', 'probe', ''))
+    parser.add_argument('-u', '--purpose', help="if given, this value will limit the output files to those designed for the given purposes.", choices=('enroll', 'probe', ''))
     parser.add_argument('-g', '--group', help="if given, this value will limit the output files to those belonging to a particular protocolar group.", choices=('dev', 'eval', 'world', 'optional_world_1', 'optional_world_2', ''))
     parser.add_argument('--self-test', dest="selftest", action='store_true', help=argparse.SUPPRESS)
     parser.set_defaults(func=dumplist) #action

bob/db/voxforge/test.py

@@ -41,13 +41,13 @@ def test_query():
 
   assert len(db.objects(groups='world')) == 3148 # 3148 samples in the world set
 
-  assert len(db.objects(groups='dev', purposes='enrol')) == 1304 # 1304 samples for enrollment in the dev set
-  assert len(db.objects(groups='dev', purposes='enrol', model_ids='Dcoetzee')) == 240 # 240 samples to enroll model 'Dcoetzee' in the dev set
-  assert len(db.objects(groups='dev', purposes='enrol', model_ids='rortiz')) == 0 # 0 samples to enroll model 'rortiz' (it is an eval model)
+  assert len(db.objects(groups='dev', purposes='enroll')) == 1304 # 1304 samples for enrollment in the dev set
+  assert len(db.objects(groups='dev', purposes='enroll', model_ids='Dcoetzee')) == 240 # 240 samples to enroll model 'Dcoetzee' in the dev set
+  assert len(db.objects(groups='dev', purposes='enroll', model_ids='rortiz')) == 0 # 0 samples to enroll model 'rortiz' (it is an eval model)
   assert len(db.objects(groups='dev', purposes='probe')) == 300 # 300 samples as probes in the dev set
 
-  assert len(db.objects(groups='eval', purposes='enrol')) == 1509 # 1509 samples for enrollment in the eval set
-  assert len(db.objects(groups='eval', purposes='enrol', model_ids='rortiz')) == 120 # 120 samples to enroll model 'rortiz' in the eval set
-  assert len(db.objects(groups='eval', purposes='enrol', model_ids='Dcoetzee')) == 0 # 0 samples to enroll model 'Dcoetzee' (it is a dev model)
+  assert len(db.objects(groups='eval', purposes='enroll')) == 1509 # 1509 samples for enrollment in the eval set
+  assert len(db.objects(groups='eval', purposes='enroll', model_ids='rortiz')) == 120 # 120 samples to enroll model 'rortiz' in the eval set
+  assert len(db.objects(groups='eval', purposes='enroll', model_ids='Dcoetzee')) == 0 # 0 samples to enroll model 'Dcoetzee' (it is a dev model)
   assert len(db.objects(groups='eval', purposes='probe')) == 300 # 300 samples as probes in the eval set
 

doc/conf.py

@@ -3,21 +3,13 @@
 # Andre Anjos <andre.anjos@idiap.ch>
 # Mon 13 Aug 2012 12:38:15 CEST
 #
-# Copyright (C) 2011-2012 Idiap Research Institute, Martigny, Switzerland
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, version 3 of the License.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
+
+import os
+import sys
+import glob
+import pkg_resources
 
-import sys, os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -71,16 +63,17 @@ project = u'BANCA Database (Bob API)'
 import time
 copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
 
+# Grab the setup entry
+distribution = pkg_resources.require('bob.db.voxforge')[0]
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-from bob.db.voxforge.driver import Interface
-version = Interface().version()
+version = distribution.version
 # The full version, including alpha/beta/rc tags.
-release = version
-
+release = distribution.version
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
@@ -140,12 +133,12 @@ if sphinx.__version__ >= "1.0":
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = ''
+html_logo = 'img/logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = ''
+html_favicon = 'img/favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -194,7 +187,7 @@ html_favicon = ''
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'bobdbdoc'
+htmlhelp_basename = 'bob_db_voxforge_doc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -208,7 +201,7 @@ latex_font_size = '10pt'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'bobdbman.tex', u'Bob',
+  ('index', 'bob_db_voxforge.tex', u'Bob',
    u'Biometrics Group, Idiap Research Institute', 'manual'),
 ]
 
@@ -246,40 +239,15 @@ man_pages = [
     ('index', 'bob', u'BANCA (Bob API) Documentation', [u'Idiap Research Institute'], 1)
 ]
 
-
-# We want to remove all private (i.e. _. or __.__) members
-# that are not in the list of accepted functions
-accepted_private_functions = ['__call__']
-
-def member_function_test(app, what, name, obj, skip, options):
-  # test if we have a private function
-  if len(name) > 1 and name[0] == '_':
-    # test if this private function should be allowed
-    if name not in accepted_private_functions:
-      # omit privat functions that are not in the list of accepted private functions
-      return True
-    else:
-      # test if the method is documented
-      if not hasattr(obj, '__doc__') or not obj.__doc__:
-        return True
-
-  # Skips selected members in auto-generated documentation. Unfortunately, old
-  # versions of Boost.Python will not generate a __self__ member for static
-  # methods and that screws-up Sphinx processing.
-  if sphinx.__version__ < "1.0":
-    # We have to remove objects that do not have a __self__ attribute set
-    import types
-    if isinstance(obj, types.BuiltinFunctionType) and \
-      not hasattr(obj, '__self__') and what == 'class':
-        app.warn("Skipping %s %s (no __self__)" % (what, name))
-        return True
-
-    return False
-
 # Default processing flags for sphinx
 autoclass_content = 'both'
 autodoc_member_order = 'bysource'
-autodoc_default_flags = ['members', 'undoc-members', 'special-members', 'inherited-members', 'show-inheritance']
+autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
+
+# For inter-documentation mapping:
+from bob.extension.utils import link_documentation
+intersphinx_mapping = link_documentation(['python', 'bob.db.base', 'bob.db.verification.utils', 'bob.db.verification.filelist', 'bob.spear'])
+
 
 def setup(app):
-  app.connect('autodoc-skip-member', member_function_test)
+  pass

doc/guide.rst

@@ -6,5 +6,18 @@
  User's Guide
 ==============
 
+This package contains the access API and descriptions for the Voxforge_ database.
+It only contains the Bob_ accessor methods to use the database directly from python, with our certified protocols.
+
+The Database Interface
+----------------------
+
+The :py:class:`bob.db.voxforge.Database` complies with the standard biometric verification database as described in :ref:`commons`, by implementing the  :py:class:`bob.db.verification.filelist.Database`.
+
+
 .. todo::
-   Write users guide.
+   Explain the particularities of the :py:class:`bob.db.voxforge.Database` database.
+
+.. _bob: https://www.idiap.ch/software/bob
+.. _voxforge: http://www.voxforge.org
+

doc/index.rst

@@ -2,12 +2,64 @@
 .. @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
 .. @date:   Tue Aug 26 09:42:18 CEST 2014
 
-=======================================
- BANCA Database Verification Protocols
-=======================================
+==========================================
+ Voxforge Database Verification Protocols
+==========================================
 
 .. todolist::
 
+=======================================================
+ Speaker recognition protocol on the Voxforge Database
+=======================================================
+
+`Voxforge`_ offers a collection transcribed speech for use with **Free** and **Open Source Speech Recognition Engines**.
+In this package, we design a speaker recognition protocol that uses a **small subset of the english audio files** (only 6561 files) belonging to **30 speakers** randomly selected.
+This subset is split into three equivalent parts: Training (10 speakers), Development (10 speakers) and Test (10 speakers) sets.
+
+This package serves as a toy example of speaker recognition database while testing :ref:`bob.spear <bob.spear>`.
+
+:ref:`bob.spear <bob.spear>` is developed at Idiap_ during its participation to the `NIST SRE 2012 evaluation`_.
+If you use this package and/or its results, please cite the following publications:
+
+1. The original paper presented at the NIST SRE 2012 workshop:
+
+   .. code-block:: latex
+
+      @inproceedings{Khoury_NISTSRE_2012,
+        author = {Khoury, Elie and El Shafey, Laurent and Marcel, S\'ebastien},
+        title = {The Idiap Speaker Recognition Evaluation System at NIST SRE 2012},
+        booktitle = {NIST Speaker Recognition Conference},
+        year = {2012},
+        month = dec,
+        location = {Orlando, USA},
+        organization = {NIST},
+        pdf = {http://publications.idiap.ch/downloads/papers/2012/Khoury_NISTSRE_2012.pdf}
+      }
+
+2. Bob_ as the core framework used to run the experiments:
+
+   .. code-block:: latex
+
+      @inproceedings{Anjos_ACMMM_2012,
+        author = {Anjos, Andr\'e and El Shafey, Laurent and Wallace, Roy and G\"unther, Manuel and McCool, Christopher and Marcel, S\'ebastien},
+        title = {Bob: a free signal processing and machine learning toolbox for researchers},
+        year = {2012},
+        month = oct,
+        booktitle = {20th ACM Conference on Multimedia Systems (ACMMM), Nara, Japan},
+        publisher = {ACM Press},
+        pdf = {http://publications.idiap.ch/downloads/papers/2012/Anjos_Bob_ACMMM12.pdf}
+     }
+
+Getting the data
+----------------
+
+The original data can be downloaded directly from Voxforge_, or by running ``./scripts/download_and_untar.sh`` that takes as input the path in which the data will be stored:
+
+.. code-block:: sh
+
+  $ ./scripts/download_and_untar.sh PATH/TO/WAV/DIRECTORY
+
+
 Documentation
 -------------
 
@@ -24,3 +76,9 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _bob: https://www.idiap.ch/software/bob
+.. _voxforge: http://www.voxforge.org
+.. _nist sre 2012 evaluation: http://www.nist.gov/itl/iad/mig/sre12.cfm
+.. _idiap: http://www.idiap.ch
+
+

doc/py_api.rst

@@ -2,8 +2,8 @@
 .. Laurent El Shafey <laurent.el-shafey@idiap.ch>
 .. Tue 28 Aug 2012 18:09:40 CEST
 
-================
- BANCA Database
-================
+============
+ Python API
+============
 
 .. automodule:: bob.db.voxforge

setup.py

@@ -53,6 +53,7 @@ setup(
     },
 
     classifiers = [
+      'Framework :: Bob',
       'Development Status :: 4 - Beta',
       'Intended Audience :: Education',
       'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',