Adapted and corrected the documentation

.gitignore

@@ -3,7 +3,6 @@
 *.pyc
 *.so
 *.dylib
-CMakeLists.txt
 bin
 eggs
 parts

.travis.yml

@@ -9,6 +9,7 @@ matrix:
     - SCIPYSPEC===0.12.0
     - secure: gBLc7oAwSQZtxHf/olpoPS1dmlA9nTcaFBBSTi62BPth8d8BlPrLoGluWuEIyyjbWgoVLbzNHLG0KL1zsjoV8ZWMIed7WSLZBGu+wU8K2gvgpTKwsFb0OEAix5bE2/QrMZtdPDM+izOMPlFGTT2xF2NFd3gn3N9dJxntTq/hcZA=
     - secure: aMJ2P2EwYHrsweAFa8X9cm2nrBFFDGoRBH98cXAbOfkgrbHseoIEZN9nx/ItYteGZqv8DOi0lMlucSxU5OhvdLN+YoGn67TIb7kHtux8V2XfO57P5d/fFkJjqBVbBzXolqHvIXVkDEdriaDvFrvIospPiaPgaL8JdqcHA5k7lRQ=
+    - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
   - python: 3.2
     env:
     - NUMPYSPEC===1.8.0
@@ -16,11 +17,11 @@ matrix:
 before_install:
 - sudo add-apt-repository -y ppa:biometrics/bob
 - sudo apt-get update -qq
-- sudo apt-get install -qq --force-yes libjpeg8-dev libnetpbm10-dev libpng12-dev libtiff4-dev libgif-dev libboost-all-dev libblitz1-dev libhdf5-serial-dev libvl-dev dvipng texlive-latex-base texlive-latex-extra texlive-math-extra libatlas-dev libatlas-base-dev liblapack-dev
+- sudo apt-get install -qq --force-yes libjpeg8-dev libnetpbm10-dev libpng12-dev libtiff4-dev libgif-dev libboost-all-dev libblitz1-dev libhdf5-serial-dev libvl-dev dvipng texlive-latex-base texlive-latex-extra texlive-math-extra texlive-latex-recommended texlive-fonts-recommended libatlas-dev libatlas-base-dev liblapack-dev
 - 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 scipy$SCIPYSPEC 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 scipy$SCIPYSPEC 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,29 +2,24 @@
 .. 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.example.faceverify/index.html
+.. image:: http://img.shields.io/badge/docs-latest-orange.png
+   :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.example.faceverify/master/index.html
 .. image:: https://travis-ci.org/bioidiap/bob.example.faceverify.svg?branch=master
    :target: https://travis-ci.org/bioidiap/bob.example.faceverify
 .. image:: https://coveralls.io/repos/bioidiap/bob.example.faceverify/badge.png
    :target: https://coveralls.io/r/bioidiap/bob.example.faceverify
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.example.faceverify.png
-   :target: https://github.com/bioidiap/bob.example.faceverify
+.. image:: https://img.shields.io/badge/github-master-0000c0.png
+   :target: https://github.com/bioidiap/bob.example.faceverify/tree/master
 .. image:: http://img.shields.io/pypi/v/bob.example.faceverify.png
    :target: https://pypi.python.org/pypi/bob.example.faceverify
 .. image:: http://img.shields.io/pypi/dm/bob.example.faceverify.png
    :target: https://pypi.python.org/pypi/bob.example.faceverify
 
-
-=======================================
- Exemplary Face Verification Using Bob
-=======================================
-
-.. note::
-  If you are reading this page through our GitHub portal and not through PyPI, note the development tip of the package may not be stable or become unstable in a matter of moments.
-
-  Go to http://pypi.python.org/pypi/bob.example.faceverify to download the latest stable version of this package.
-
-Overview
---------
+===================================================
+ Exemplary Face Verification Experiments Using Bob
+===================================================
 
 This example demonstrates how to use Bob to build three different face verification systems.
 It includes examples with three different complexities:
@@ -33,43 +28,21 @@ It includes examples with three different complexities:
 * An example using Gabor jets in a grid graph
 * An example building an UBM/GMM model on top of DCT blocks.
 
-Requirements
-------------
-
-To use this example, you will require the AT&T database.
-
-The AT&T database
-.................
-The AT&T image database is quite small, but sufficient to show how the face verification methods work.
-Still, the results may not be meaningful.
-One good thing about the AT&T database is that it is freely available.
-You can download it from http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html.
+The face verification experiments are executed on the `AT&T`_ database, which is a toy database that is perfectly useful for this example, but **not** to publish scientific papers.
 
-Download
---------
 
-Finally, to download this package, you can extract the .zip file from the link below, or you open a shell in a directory of your choice and call::
-
-  $ wget https://pypi.python.org/packages/source/b/bob.example.faceverify/bob.example.faceverify-<version>.zip
-  $ unzip bob.example.faceverify-<version>.zip
-  $ cd bob.example.faceverify-<version>
-
-where <version> should be replaced with a (the current) version of this package, or you can clone our git repository::
-
-  $ git clone https://github.com/bioidiap/bob.example.faceverify.git
-  $ cd bob.example.faceverify
-
-Afterwards, please call::
-
-  $ python bootstrap.py
-  $ ./bin/buildout
-
-to generate the scripts that, amongst others, will run the face verification algorithms. Please verify your installation by running the test cases. For more details, please refer to the documentation, which you might create and open yourself by::
+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.
 
-  $ ./bin/sphinx-build doc sphinx
-  $ firefox sphinx/index.html
+Documentation
+-------------
+For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.example.faceverify/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.example.faceverify/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.
 
-(or use any other browser of your choice).
+.. _bob: https://www.idiap.ch/software/bob
+.. _at&t: http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
 
-If you have questions to or problems with this package, please send a request to bob-devel@googlegroups.com, or file a bug under https://github.com/bioidiap/bob.example.faceverify/issues.
 

doc/Makefile

-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = ../bin/sphinx-build
-PAPER         =
-BUILDDIR      = .
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html doctest
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/html $(BUILDDIR)/doctest $(BUILDDIR)/doctrees
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."

doc/conf.py

-# -*- coding: utf-8 -*-
+#!/usr/bin/env python
+# vim: set fileencoding=utf-8 :
+# Manuel Guenther <manuel.guenther@idiap.ch>
+# Wed Nov  5 19:37:47 CET 2014
 #
-# FaceRecLib documentation build configuration file, created by
-# sphinx-quickstart on Wed Jan 25 17:23:57 2012.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# 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
@@ -37,6 +35,23 @@ extensions = [
   'matplotlib.sphinxext.plot_directive',
 ]
 
+# The viewcode extension appeared only on Sphinx >= 1.0.0
+import sphinx
+if sphinx.__version__ >= "1.0":
+  extensions.append('sphinx.ext.viewcode')
+
+# The viewcode extension appeared only on Sphinx >= 1.0.0
+import sphinx
+if sphinx.__version__ >= "1.0":
+  extensions.append('sphinx.ext.viewcode')
+
+# Always includes todos
+todo_include_todos = True
+
+# If we are on OSX, the 'dvipng' path maybe different
+dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
+if os.path.exists(dvipng_osx): pngmath_dvipng = dvipng_osx
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -50,17 +65,21 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'bob.example.faceverify'
-copyright = u'2012, Manuel Guenther'
+project = u'Exemplary Face Verification Experiments using Bob'
+import time
+copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
+
+# Grab the setup entry
+distribution = pkg_resources.require('bob.example.faceverify')[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.
-version = '0.1'
+version = distribution.version
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = distribution.version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -101,7 +120,8 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+if sphinx.__version__ >= "1.0":
+  html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -116,16 +136,16 @@ html_theme = 'default'
 #html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+#html_short_title = 'bob'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+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 = None
+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,
@@ -174,27 +194,27 @@ html_theme = 'default'
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'bob.example.faceverify.doc'
+htmlhelp_basename = 'bob_example_faceverify_doc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
 
 # The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
+latex_paper_size = 'a4'
 
 # The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+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', 'FaceRecLib.tex', u'FaceRecLib Documentation',
-#   u'Laurent El Shafey', 'manual'),
-#]
+latex_documents = [
+  ('index', 'bob_example_faceverify.tex', u'Bob',
+   u'Biometrics Group, Idiap Research Institute', 'manual'),
+]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+latex_logo = ''
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -215,12 +235,26 @@ htmlhelp_basename = 'bob.example.faceverify.doc'
 # If false, no module index is generated.
 #latex_domain_indices = True
 
+# Included after all input documents
+rst_epilog = ''
 
 # -- Options for manual page output --------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'bob.example.faceverify', u'Documentation for the examples how to use Bob for face verification',
-     [u'Manuel Guenther'], 1)
+    ('index', 'bob', u'Exemplary Face Verification Experiments using Bob', [u'Idiap Research Institute'], 1)
 ]
+
+# Default processing flags for sphinx
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'
+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', 'numpy', 'scipy', 'bob.io.base', 'bob.measure', 'bob.ip.base', 'bob.ip.gabor', 'bob.learn.linear', 'bob.learn.misc', 'bob.db.atnt', 'bob.db.verification.utils'])
+
+
+def setup(app):
+  pass

doc/examples.rst

@@ -2,9 +2,9 @@
 .. Manuel Guenther <manuek.guether@idiap.ch>
 .. Mon Aug 25 19:15:29 CEST 2014
 
-======================
- Running the examples
-======================
+==========================================
+ Running the Face Recognition Experiments
+==========================================
 
 .. testsetup:: *
 
@@ -42,7 +42,7 @@ If you installed the image database in another folder than ``Database``, please
 
   $ ./bin/eigenface.py <AT&T_DATABASE_DIR>
 
-There are three example scripts:
+There are three experiment scripts:
 
 .. code-block:: sh
 
@@ -52,10 +52,10 @@ There are three example scripts:
 
 that perform more or less complicated face verification experiments using an *unbiased* evaluation protocol.
 Each experiment creates an ROC curve that contains the final verification result of the test.
-The generated files will be ``eigenface.pdf``, ``gabor_graph.pdf``, and ``dct_ubm.pdf``.
+The generated files will be ``eigenface.pdf``, ``gabor_graph.pdf`` and ``dct_ubm.pdf``, respectively.
 
 Since the complexity of the algorithms increase, the expected execution time of them differ a lot.
-While the eigenface example should be finished in a couple of seconds, the Gabor phase example could take some minutes, and the UBM/GMM model needs in the order of half an hour to compute.
+While the eigenface experiment should be finished in a couple of seconds, the Gabor graph experiment could take some minutes, and the UBM/GMM model needs in the order of half an hour to compute.
 
 .. note::
 
@@ -63,16 +63,20 @@ While the eigenface example should be finished in a couple of seconds, the Gabor
   Here, only the concepts of the functions should be clarified, while the source files contain code that is better arranged and computes faster.
 
 
-The eigenface example
+In this small example, we use the :ref:`bob.db.atnt <bob.db.atnt>` database.
+This database is compatible with all other :py:class:`bob.db.verification.utils.Database`\s, so any other :ref:`verification_databases` can be used in a direct replacement of :ref:`bob.db.atnt <bob.db.atnt>`.
+
+
+The Eigenface Example
 ~~~~~~~~~~~~~~~~~~~~~
 The eigenface example follows the work-flow that is presented in the original paper *Eigenfaces for Recognition* [TP91]_ by Turk and Pentland.
-First, it creates an object to query the database:
+First, it creates an :py:class:`bob.db.atnt.Database` object to query the :ref:`bob.db.atnt <bob.db.atnt>` database:
 
 .. doctest::
 
   >>> atnt_db = bob.db.atnt.Database()
 
-For training the projection matrix, the training images (which are in gray-scale) need to be read:
+For training the projection matrix, the training images (which are in gray-scale) are be read using the generic :py:func:`bob.io.base.load` function, which returns the data as a :py:class:`numpy.ndarray`:
 
 .. doctest::
 
@@ -83,13 +87,13 @@ For training the projection matrix, the training images (which are in gray-scale
   ...   # linearize pixels
   ...   training_feature = training_image.flatten()
 
-Since the images are already cropped, they can simply be linearized (converted into one long vector) and put into a 2D array with one sample in each row:
+Since the face images in the AT&T database are already cropped, they can simply be linearized (converted into one long vector) and put into a 2D array with one sample in each row, and no :py:class:`bob.ip.base.FaceEyesNorm` needs to be applied to align the faces using the :py:meth:`bob.db.verification.utils.Database.annotations` of the eyes:
 
 .. doctest::
 
   >>> training_set = numpy.vstack(training_features)
 
-which is used to train a :py:class:`bob.learn.linear.Machine`:
+which is then used to train a :py:class:`bob.learn.linear.Machine` using a :py:class:`bob.learn.linear.PCATrainer`:
 
 .. doctest::
 
@@ -102,7 +106,7 @@ After training, the model and probe images are loaded, linearized, and projected
 
 .. doctest::
 
-  >>> model_image_files = atnt_db.objects(groups = 'dev', purposes = 'enrol')
+  >>> model_image_files = atnt_db.objects(groups = 'dev', purposes = 'enroll')
   >>> for model_file in model_image_files:
   ...   # load image
   ...   model_image = bob.io.base.load(model_file.make_path(...)) #doctest:+SKIP
@@ -125,10 +129,10 @@ To follow the evaluation protocol, we *enroll* a client model for each client, s
   ...   # query the database for the model id of the current file id
   ...   model_id = atnt_db.get_client_id_from_file_id(model_image_id)
   ...   # append feature for the current model id
-  ...   #models[model_id].append(model_features[model_feature_id])
+  ...   models[model_id].append(model_features[model_feature_id]) #doctest:+SKIP
 
 
-To compute the verification result, each model feature is compared to each probe feature by computing the Euclidean distance:
+To compute the verification result, each model feature is compared to each probe feature by computing the :py:func:`scipy.spatial.distance.euclidean` distance:
 
 .. doctest::
 
@@ -140,7 +144,7 @@ To compute the verification result, each model feature is compared to each probe
 Finally, all scores of one model and one probe are averaged to get the final score for this pair.
 
 The results are divided into a list of positive scores (model and probe are from the same identity) and a a list of negative scores (identities of model and probe differ).
-Using these lists, the ROC curve is plotted:
+Using these lists, the ROC curve is plotted using functionality from :ref:`bob.measure <bob.measure>`:
 
 .. doctest::
 
@@ -172,7 +176,7 @@ The expected result is: FAR 9.15% and FRR 9% at threshold -9276.2
 Gabor jet comparisons
 ~~~~~~~~~~~~~~~~~~~~~
 A better face verification example uses Gabor jet features [WFKM97]_ .
-In this example we do not define a face graph, but instead we use the Gabor jets at several grid positions in the image.
+In this example we do not define a face graph, but instead we use the :py:class:`bob.ip.gabor.Jet`\s at several grid positions in the image.
 To do that, we define:
 
 .. doctest::
@@ -197,7 +201,7 @@ Here is the code for the model graphs only:
 .. doctest::
 
   >>> gabor_wavelet_transform = bob.ip.gabor.Transform()
-  >>> model_image_files = atnt_db.objects(groups = 'dev', purposes = 'enrol')
+  >>> model_image_files = atnt_db.objects(groups = 'dev', purposes = 'enroll')
   >>> for model_file in model_image_files:
   ...   # load image
   ...   model_image = bob.io.base.load(model_file.make_path(...)) #doctest:+SKIP
@@ -207,7 +211,7 @@ Here is the code for the model graphs only:
 
 For model enrollment, as above we simply collect all enrollment features.
 To compare the Gabor graphs, several methods can be applied.
-Again, many choices for the Gabor jet comparison exist, here we take a novel Gabor phase based similarity function [GHW12]_:
+Again, many choices for the Gabor jet comparison exist, here we take a novel Gabor phase based :py:class:`bob.ip.gabor.Similarity` function [GHW12]_:
 
 .. doctest::
 
@@ -239,7 +243,7 @@ The UBM/GMM modeling of DCT Blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The last example shows a quite complicated, but successful algorithm.
 The first step is the feature extraction of the training image features and the collection of them in a 2D array.
-In this experiment we will use *Discrete Cosine Transform* (DCT) block features [MM09]_:
+In this experiment we will use *Discrete Cosine Transform* (DCT) block features using :py:class:`bob.ip.base.DCTFeatures` [MM09]_:
 
 .. doctest::
 
@@ -252,7 +256,7 @@ In this experiment we will use *Discrete Cosine Transform* (DCT) block features
   ...   training_features = dct_extractor(training_image)
 
 Hence, from every image, several DCT block features are extracted independently.
-All these features are mixed together to build the training set
+All these features are mixed together to build the training set:
 
 .. code-block:: python
 
@@ -285,7 +289,6 @@ and a :py:class:`bob.learn.misc.ML_GMMTrainer` is used to compute the actual UBM
   >>> trainer = bob.learn.misc.ML_GMMTrainer()
   >>> trainer.train(ubm, training_set)
 
-
 After UBM training, the next step is the model enrollment.
 Here, a separate GMM model is generated by shifting the UBM towards the mean of the model features [MM09]_.
 For this purpose, we need to get the model images sorted by identity:
@@ -302,7 +305,7 @@ For that purpose, a :py:class:`bob.learn.misc.MAP_GMMTrainer` is used:
   >>> gmm_trainer = bob.learn.misc.MAP_GMMTrainer()
   >>> # ... initialize GMM trainer ...
   >>> for model_id in model_ids:
-  ...   model_files = db.objects(groups = 'test', purposes = 'enrol', client_ids = model_id)
+  ...   model_files = db.objects(groups = 'test', purposes = 'enroll', client_ids = model_id)
   ...   model_feature_set_list = []
   ...   for model_file in model_files:
   ...     # ... load model image ...
@@ -315,7 +318,7 @@ For that purpose, a :py:class:`bob.learn.misc.MAP_GMMTrainer` is used:
 
 Also the probe image need some processing.
 First, of course, the DCT features are extracted.
-Afterward, the statistics for each probe file are generated:
+Afterward, the :py:class:`bob.learn.misc.GMMStats` statistics for each probe file are generated:
 
 .. code-block:: python
 
@@ -327,7 +330,7 @@ Afterward, the statistics for each probe file are generated:
   ...   gmm_stats.init()
   ...   ubm.acc_statistics(probe_dct_blocks, probe_gmm_stats)
 
-Finally, the scores for the probe files are computed using the function **bob.machine.linear_scoring**:
+Finally, the scores for the probe files are computed using the :py:func:`bob.learn.misc.linear_scoring` function:
 
 .. code-block:: python
 

doc/index.rst

-.. FaceRecLib documentation master file, created by
-   sphinx-quickstart on Wed Jan 25 17:23:57 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. vim: set fileencoding=utf-8 :
+.. @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
+.. @date:   Wed Nov  5 19:56:23 CET 2014
 
-Welcome to the documentation of the face verification examples!
-===============================================================
+.. _bob.example.faceverify:
 
-Contents:
+===================================================
+ Exemplary Face Verification Experiments Using Bob
+===================================================
+
+This example demonstrates how to use Bob_ to build three different face verification systems.
+It includes examples with three different complexities:
+
+* A simple eigenface based example
+* An example using Gabor jets in a grid graph
+* An example building an UBM/GMM model on top of DCT blocks.
+
+The face verification experiments are executed using the protocols for the `AT&T`_  database implemented in :ref:`bob.db.atnt <bob.db.atnt>`.
+
+.. warning::
+   The `AT&T`_ database is a toy database that is perfectly useful for this example, but **not** to publish scientific papers.
 
 .. toctree::
    :maxdepth: 2
@@ -21,3 +33,7 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+
+.. _bob: https://www.idiap.ch/software/bob
+.. _at&t: http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
+

doc/installation.rst

-=============
+.. vim: set fileencoding=utf-8 :
+.. @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
+.. @date:   Wed Nov  5 19:56:23 CET 2014
+
+==============
  Installation
-=============
+==============
 
 .. note::
 
   To follow these instructions locally you will need a local copy of this package.
-  You can obtain a copy by:
-
-  .. code-block:: sh
+  Please go to the `PyPI page of this package <http://pypi.python.org/pypi/bob.example.faceverify>`_ and download the ``.zip`` file using the ``Download`` button in the top-right of the page.
+  Unzip the package in a directory of your choice and open a console window in this directory.
 
-    $ wget https://pypi.python.org/packages/source/b/bob.example.faceverify/bob.example.faceverify-<version>.zip
-    $ unzip bob.example.faceverify-<version>.zip
-    $ cd bob.example.faceverify-<version>
-
-  where ``<version>`` is the latest version of the package that you can find under https://pypi.python.org/pypi/bob.example.faceverify, or by cloning our git repository
+  You also might want to use the latest version of this package, which you can obtain from GitHub_:
 
   .. code-block:: sh
 
     $ git clone https://github.com/bioidiap/bob.example.faceverify.git
     $ cd bob.example.faceverify
 
-Installation of this example uses the `buildout <http://www.buildout.org/>`_ build environment.
+Installation of this example uses the `buildout <http://www.buildout.org/>`_ building environment.
 You don't need to understand its inner workings to use this package.
 Here is a recipe to get you started:
 
@@ -30,43 +29,32 @@ Here is a recipe to get you started:
   $ ./bin/buildout
 
 These 2 commands should download and install all non-installed dependencies and get you a fully operational test and development environment.
+Particularly, it will download and compile all required packages of Bob_.
+Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ of Bob_ for your operating system.
 
 .. note::
-
-  The python shell used in the first line of the previous command set determines the python interpreter that will be used for all scripts developed inside this package.
-  Because this package makes use of `Bob <http://www.idiap.ch/software/bob>`_, you must make sure that the ``bootstrap.py`` script is called with the **same** interpreter used to build Bob, or unexpected problems might occur.
-
-  If Bob is installed by the administrator of your system, it is safe to consider it uses the default python interpreter.
-  In this case, the above 2 command lines should work as expected.
+   Compiling the packages of Bob_ might take a while.
 
 
-
-Downloading the test database
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Download the Test Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 The images that are required to run the test are not included in this package, but they are freely downloadable from http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
 
 Unpack the database in a directory that fits you.
-The easiest solution is to create a subdirectory ``Database`` in this package.
+The easiest solution is to create a sub-directory ``Database`` in this package.
 If you decide to put the data somewhere else, please remember the image directory.
 
-.. note ::
-
-  If you are at Idiap, the AT&T database is located at ``/idiap/group/biometric/databases/orl``.
-  To ease up the usage of the examples, you can generate a link to the database:
-
-  .. code-block:: sh
-
-    $ ln -s /idiap/group/biometric/databases/orl Database
-
 
-Verify your installation
+Verify your Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 To verify your installation, you might want to run the unit tests that are provided with this package.
-For this, the AT&T database is required to be either in the ``Database`` subdirectory of this package (see above), or that the ``ATNT_DATABASE_DIRECTORY`` environment variable points to your database directory.
+For this, the AT&T database is required to be either in the ``Database`` sub-directory of this package (see above), or that the ``ATNT_DATABASE_DIRECTORY`` environment variable points to your database directory.
 At Idiap, you might want to use:
 
 .. code-block:: sh
 
-  $ export ATNT_DATABASE_DIRECTORY=/idiap/group/biometric/databases/orl
+  $ export ATNT_DATABASE_DIRECTORY=/YOUR/ATNT/IMAGE/DIRECTORY
   $ bin/nosetests -v
 
+.. _bob: https://www.idiap.ch/software/bob
+.. _github: https://www.github.com

setup.py

@@ -29,7 +29,7 @@ setup(
     # information before releasing code publicly.
     name='bob.example.faceverify',
     version='2.0.0a0',
-    description='Example for using Bob to create face verification systems',
+    description='Example for using Bob to create three distinct face verification systems',
     url='http://pypi.python.org/pypi/bob.example.faceverify',
     license='GPLv3',
     author='Manuel Guenther',
@@ -78,15 +78,10 @@ setup(
         'gabor_graph.py = bob.example.faceverify.gabor_graph:main',
         'dct_ubm.py = bob.example.faceverify.dct_ubm:main'
       ],
-
-       # bob unittest declaration
-      'bob.test':
-      [
-        'faceverify = faceverify.tests:FaceVerifyExampleTest',
-      ],
     },
 
     classifiers = [
+      'Framework :: Bob',
       'Development Status :: 4 - Beta',
       'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
       'Intended Audience :: Education',