New README and documentation strategy

.gitignore

@@ -1,13 +1,19 @@
 *~
 *.swp
 *.pyc
+*.so
+*.dylib
 bin
 eggs
 parts
 .installed.cfg
 .mr.developer.cfg
 *.egg-info
-src
 develop-eggs
 sphinx
 dist
+.nfs*
+.gdb_history
+build
+*.egg
+src/

.travis.yml

@@ -6,6 +6,7 @@ matrix:
     env:
     - secure: G+01O0hR4OdUjV0rmzydDlVhrJOcVDBByecGnORLT9LV1qSd3IU04de7AfzkZhnhl58UxmmQsxd+XqPaCJoU/uTWKa0GW0BCJSxmLxx8cXco3Y8yV03zbBRJC8rbX7O+jrlx+6Js+CFpTfm+MlOXeeGAbky5gr1KZQD2pXqr+0w=
     - secure: XUeglE6tOR0dckxT/2WPQivRY3n3tsWYnFbR1oQk17p+7o5/S5rXYxR7PvL9E8k4pprqFf54IGMVe41F5Q8k/5ZanAVRBKSnvod9or1INmqXgsMDS9yUjO0jTHnrazSn4jNIUhWd/7+1VuxdIPxUSBfVOr+9ow8IrQorQqc7eOc=
+    - 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 libsvm-dev
+- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev libatlas-dev libatlas-base-dev liblapack-dev libsvm-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

@@ -1,96 +1,50 @@
+.. vim: set fileencoding=utf-8 :
+.. Manuel Guenther <manuel.guenther@idiap.ch>
+.. Fri Oct 31 14:18:57 CET 2014
+
+.. image:: http://img.shields.io/badge/docs-stable-yellow.png
+   :target: http://pythonhosted.org/bob.db.casia_fasd/index.html
+.. image:: http://img.shields.io/badge/docs-latest-orange.png
+   :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.casia_fasd/master/index.html
 .. image:: https://travis-ci.org/bioidiap/bob.db.casia_fasd.svg?branch=master
    :target: https://travis-ci.org/bioidiap/bob.db.casia_fasd
 .. image:: https://coveralls.io/repos/bioidiap/bob.db.casia_fasd/badge.png
    :target: https://coveralls.io/r/bioidiap/bob.db.casia_fasd
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.db.casia_fasd.png
-   :target: https://github.com/bioidiap/bob.db.casia_fasd
+.. image:: https://img.shields.io/badge/github-master-0000c0.png
+   :target: https://github.com/bioidiap/bob.db.casia_fasd/tree/master
 .. image:: http://img.shields.io/pypi/v/bob.db.casia_fasd.png
    :target: https://pypi.python.org/pypi/bob.db.casia_fasd
 .. image:: http://img.shields.io/pypi/dm/bob.db.casia_fasd.png
    :target: https://pypi.python.org/pypi/bob.db.casia_fasd
+.. image:: https://img.shields.io/badge/original-data--files-a000a0.png
+   :target: http://www.cbsr.ia.ac.cn/english/FaceAntiSpoofDatabases.asp
 
-===================================
- CASIA Face Anti-Spoofing Database
-===================================
+=====================================================
+ CASIA Face Anti-Spoofing Database Interface for Bob
+=====================================================
 
-The CASIA-FASD database is a spoofing attack database which consists of three
-types of attacks: warped printed photographs, printed photographs with cut eyes
-and video attacks. The samples are taken with three types of cameras: low
-quality, normal quality and high quality.
+The CASIA-FASD database is a spoofing attack database which consists of three types of attacks: warped printed photographs, printed photographs with cut eyes and video attacks.
+The samples are taken with three types of cameras: low quality, normal quality and high quality.
 
-The actual raw data for the database should be downloaded from the original
-URL. This package only contains the `Bob <http://www.idiap.ch/software/bob/>`_
-accessor methods to use the DB directly from python, with our certified
-protocols.
+This package contains the Bob_ accessor methods to use the DB directly from python, with our certified protocols.
+The actual raw data for `CASIA FASD`_ database should be downloaded from the original URL
 
-References::
+Reference::
 
-  1. Z. Zhang, J. Yan, S. Lei, D. Yi, S. Z. Li: "A Face Antispoofing Database
-     with Diverse Attacks", In proceedings of the 5th IAPR International
-     Conference on Biometrics (ICB'12), New Delhi, India, 2012.
+  Z. Zhang, J. Yan, S. Lei, D. Yi, S. Z. Li: "A Face Antispoofing Database with Diverse Attacks", In proceedings of the 5th IAPR International Conference on Biometrics (ICB'12), New Delhi, India, 2012.
 
-You would normally not install this package unless you are maintaining it. What
-you would do instead is to tie it in at the package you need to **use** it.
-There are a few ways to achieve this:
 
-1. You can add this package as a requirement at the ``setup.py`` for your own
-   `satellite package
-   <https://github.com/idiap/bob/wiki/Virtual-Work-Environments-with-Buildout>`_
-   or to your Buildout ``.cfg`` file, if you prefer it that way. With this
-   method, this package gets automatically downloaded and installed on your
-   working environment, or
+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.
 
-2. You can manually download and install this package using commands like
-   ``easy_install`` or ``pip``.
+Documentation
+-------------
+For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.db.casia_fasd/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.casia_fasd/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 package is available in two different distribution formats:
+.. _bob: https://www.idiap.ch/software/bob
+.. _casia fasd: http://www.cbsr.ia.ac.cn/english/FaceAntiSpoofDatabases.asp
 
-1. You can download it from `PyPI <http://pypi.python.org/pypi>`_, or
-
-2. You can download it in its source form from `its git repository
-   <https://github.com/bioidiap/xbob.db.casia_fasd>`_. When you download the
-   version at the git repository, you will need to run a command to recreate
-   the backend SQLite file required for its operation. This means that the
-   database raw files must be installed somewhere in this case. With option
-   ``a`` you can run in `dummy` mode and only download the raw data files for
-   the database once you are happy with your setup.
-
-You can mix and match points 1/2 and a/b above based on your requirements. Here
-are some examples:
-
-Modify your setup.py and download from PyPI
-===========================================
-
-That is the easiest. Edit your ``setup.py`` in your satellite package and add
-the following entry in the ``install_requires`` section (note: ``...`` means
-`whatever extra stuff you may have in-between`, don't put that on your
-script)::
-
-    install_requires=[
-      ...
-      "xbob.db.casia_fasd",
-    ],
-
-Proceed normally with your ``boostrap/buildout`` steps and you should be all
-set. That means you can now import the namespace ``xbob.db.casia_fasd`` into your
-scripts.
-
-Modify your buildout.cfg and download from git
-==============================================
-
-You will need to add a dependence to `mr.developer
-<http://pypi.python.org/pypi/mr.developer/>`_ to be able to install from our
-git repositories. Your ``buildout.cfg`` file should contain the following
-lines::
-
-  [buildout]
-  ...
-  extensions = mr.developer
-  auto-checkout = *
-  eggs = bob
-         ...
-         xbob.db.casia_fasd
-
-  [sources]
-  xbob.db.casia_fasd = git https://github.com/bioidiap/xbob.db.casia_fasd.git
-  ...

bob/db/casia_fasd/__init__.py

@@ -28,7 +28,7 @@
 class Database(object):
 
   def __init__(self, foldsdir=None):
-    
+
     from .driver import Interface
     self.info = Interface()
     self.groups = ('train', 'test')
@@ -40,7 +40,7 @@ def __init__(self, foldsdir=None):
     if foldsdir == None:
       self.foldsdir = os.path.join(package_directory, 'newfolds')
     else:
-      self.foldsdir = foldsdir  
+      self.foldsdir = foldsdir
 
   def set_foldsdir(self, foldsdir):
     """Sets the directory holding the cross validation protocol of the database"""
@@ -475,4 +475,3 @@ def get_config():
 # gets sphinx autodoc done right - don't remove it
 __all__ = [_ for _ in dir() if not _.startswith('_')]
 
-#__all__ = dir()

bob/db/casia_fasd/driver.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # vim: set fileencoding=utf-8 :
 # Andre Anjos <andre.dos.anjos@gmail.com>
-# Wed 15 Aug 11:42:52 2012 
+# Wed 15 Aug 11:42:52 2012
 
 """Bob Database Driver entry-point for the CASIA Face-Antispoofing Database.
 """
@@ -33,8 +33,8 @@ def dumplist(args):
   return 0
 
 def checkfiles(args):
-  """Checks the existence of the files based on your criteria""" 
-    
+  """Checks the existence of the files based on your criteria"""
+
   #from .__init__ import Database
   db = Database()
 
@@ -86,16 +86,16 @@ def version(self):
   def type(self):
     return 'text'
 
-  def add_commands(self, parser):  
+  def add_commands(self, parser):
     """Add specific subcommands that the action "dumplist" can use"""
 
     from . import __doc__ as docs
-    
-    subparsers = self.setup_parser(parser, 
+
+    subparsers = self.setup_parser(parser,
         "CASIA Face Anti-Spoofing Database", docs)
 
     from argparse import SUPPRESS
-    
+
     db = Database()
 
     # add the dumplist command

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/>.
-
-import sys, os
+# Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
+
+import os
+import sys
+import glob
+import pkg_resources
+
 
 # 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,15 +63,17 @@
 import time
 copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
 
+# Grab the setup entry
+distribution = pkg_resources.require('bob.db.casia_fasd')[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.casia_fasd.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.
@@ -140,12 +134,12 @@
 
 # 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 +188,7 @@
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'bobdbdoc'
+htmlhelp_basename = 'bob_db_casia_fasd_doc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -208,7 +202,7 @@
 # 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_casia_fasd.tex', u'Bob',
    u'Biometrics Group, Idiap Research Institute', 'manual'),
 ]
 
@@ -247,39 +241,15 @@
 ]
 
 
-# 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', 'antispoofing.utils'])
+
 
 def setup(app):
-  app.connect('autodoc-skip-member', member_function_test)
+  pass

doc/guide.rst

@@ -6,5 +6,11 @@
  User's Guide
 ==============
 
+This database implements the face anti-spoofing database interface defined in :ref:`antispoofing.utils <antispoofing.utils>`.
+
+.. todo::
+   Adapt the link above when there is a better one inside the :ref:`antispoofing.utils <antispoofing.utils>` package.
+
+
 .. todo::
    Write users guide.

doc/index.rst

@@ -2,12 +2,17 @@
 .. @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
 .. @date:   Tue Aug 26 09:42:18 CEST 2014
 
+.. _bob.db.casia_fasd:
+
 ===================================
  CASIA Face Anti-spoofing Database
 ===================================
 
 .. todolist::
 
+.. todo::
+   upload this documentation to PythonHosted.org
+
 Documentation
 -------------