From ad914fde154f40df56ed32032bb54819f3d32b92 Mon Sep 17 00:00:00 2001
From: Manuel Guenther <manuel.guenther@idiap.ch>
Date: Wed, 29 Oct 2014 18:54:36 +0100
Subject: [PATCH] New README and documentation strategy.
---
.gitignore | 7 +----
.travis.yml | 3 ++-
README.rst | 73 ++++++++++++---------------------------------------
buildout.cfg | 1 -
doc/conf.py | 32 +++-------------------
doc/guide.rst | 14 +++++-----
setup.py | 3 ++-
7 files changed, 32 insertions(+), 101 deletions(-)
diff --git a/.gitignore b/.gitignore
index 8842b50..dae95ef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,12 +2,9 @@
*.swp
*.pyc
*.so
-*.so.*
*.dylib
-CMakeLists.txt
bin
eggs
-src
parts
.installed.cfg
.mr.developer.cfg
@@ -19,6 +16,4 @@ dist
.gdb_history
build
*.egg
-opsnr.stt
-.coverage
-.DS_Store
+src/
diff --git a/.travis.yml b/.travis.yml
index bc6869f..8eec9c7 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -9,13 +9,14 @@ matrix:
- NUMPYSPEC===1.8.0
- secure: Y3yMHo3YC++q73W2Ea+1HmhmXCBsvYX/RdUJgRBr/16S4YK17A7btqmrgDtP60PKEHY9FqwRxeK1wSa7sZhcqJ7xmi+FVvgqR5DWmlBinQ54+TaB2y0/mUQaQwTU579tzIZH+gN8arnGrqLJQINfU+NPyVDShZAGNl3iLpCGKSc=
- secure: SOMZFtB+MHMm2rBLHXzKAmKuINoEjqI1/zlC1dlNKVsCnTgxcXOkogA/YuEFUVIKmoluYTRagdJJ3mOVrHP/X7Z0GZEpZp8q19F1LrRyr1IGIle9DYYUkCV4ZYn+MwZhI7Fzkvlcm+UtjElM1Q4l7zkK/RAhcwYqTaZgZD/xADA=
+ - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
- python: 3.2
env:
- NUMPYSPEC===1.7.1
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
diff --git a/README.rst b/README.rst
index 1e7eaf6..e04faa8 100644
--- a/README.rst
+++ b/README.rst
@@ -2,76 +2,37 @@
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 22 May 2014 15:39:03 CEST
+.. image:: http://img.shields.io/badge/docs-stable-yellow.png
+ :target: http://pythonhosted.org/bob.learn.misc/index.html
+.. image:: http://img.shields.io/badge/docs-latest-orange.png
+ :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.misc/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.learn.misc.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.learn.misc
.. image:: https://coveralls.io/repos/bioidiap/bob.learn.misc/badge.png
:target: https://coveralls.io/r/bioidiap/bob.learn.misc
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.learn.misc.png
- :target: https://github.com/bioidiap/bob.learn.misc
+.. image:: https://img.shields.io/badge/github-master-0000c0.png
+ :target: https://github.com/bioidiap/bob.learn.misc/tree/master
.. image:: http://img.shields.io/pypi/v/bob.learn.misc.png
:target: https://pypi.python.org/pypi/bob.learn.misc
.. image:: http://img.shields.io/pypi/dm/bob.learn.misc.png
:target: https://pypi.python.org/pypi/bob.learn.misc
-========================================================
- Python Bindings for Miscelaneous Machines and Trainers
-========================================================
+===========================================
+ Miscelaneous Machines and Trainers in Bob
+===========================================
-This package contains a set of Pythonic bindings for Bob's machines and
-trainers which have not yet been ported into the new framework.
+This package contains various Bob's machines and trainers which have not yet been fully ported into the new framework.
+**Functionality in this package is subject to modifications**, including deletions of classes and functions (which will be moved to other packages).
Installation
------------
-
-Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
-the package and run test units.
+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.
Documentation
-------------
+For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.learn.misc/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.misc/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.
-You can generate the documentation for this package, after installation, using
-Sphinx::
-
- $ sphinx-build -b html doc sphinx
-
-This shall place in the directory ``sphinx``, the current version for the
-documentation of the package.
-
-Testing
--------
-
-You can run a set of tests using the nose test runner::
-
- $ nosetests -sv bob.learn.misc
-
-.. warning::
-
- If Bob <= 1.2.1 is installed on your python path, nose will automatically
- load the old version of the insulate plugin available in Bob, which will
- trigger the loading of incompatible shared libraries (from Bob itself), in
- to your working binary. This will cause a stack corruption. Either remove
- the centrally installed version of Bob, or build your own version of Python
- in which Bob <= 1.2.1 is not installed.
-
-You can run our documentation tests using sphinx itself::
-
- $ sphinx-build -b doctest doc sphinx
-
-You can test overall test coverage with::
-
- $ nosetests --with-coverage --cover-package=bob.learn.misc
-
-The ``coverage`` egg must be installed for this to work properly.
-
-Development
------------
-
-To develop this package, install using ``zc.buildout``, using the buildout
-configuration found on the root of the package::
-
- $ python bootstrap.py
- ...
- $ ./bin/buildout
-
-Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
-builds.
+.. _bob: https://www.idiap.ch/software/bob
diff --git a/buildout.cfg b/buildout.cfg
index e59ad73..bf3e24d 100644
--- a/buildout.cfg
+++ b/buildout.cfg
@@ -22,7 +22,6 @@ develop = src/bob.extension
debug = true
verbose = true
newest = false
-prefixes = /idiap/group/torch5spro/externals/py278/usr
[sources]
bob.extension = git https://github.com/bioidiap/bob.extension
diff --git a/doc/conf.py b/doc/conf.py
index c112d53..1324990 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -249,36 +249,10 @@ autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
-def smaller_than(v1, v2):
- """Compares scipy/numpy version numbers"""
-
- c1 = v1.split('.')
- c2 = v2.split('.')[:len(c1)] #clip to the compared version
- for i, k in enumerate(c2):
- n1 = c1[i]
- n2 = c2[i]
- try:
- n1 = int(n1)
- n2 = int(n2)
- except ValueError:
- n1 = str(n1)
- n2 = str(n2)
- if n1 > n2: return False
- return True
-
-# Some name mangling to find the correct sphinx manuals for some packages
-numpy_version = __import__('numpy').version.version
-if smaller_than(numpy_version, '1.5.z'):
- numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
-else:
- numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
-numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version
-
# For inter-documentation mapping:
-intersphinx_mapping = {
- 'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None,
- numpy_manual: None,
- }
+from bob.extension.utils import link_documentation
+intersphinx_mapping = link_documentation()
+
def setup(app):
pass
diff --git a/doc/guide.rst b/doc/guide.rst
index e174fd4..7010dd6 100644
--- a/doc/guide.rst
+++ b/doc/guide.rst
@@ -212,7 +212,7 @@ Once the :py:class:`bob.learn.misc.JFAMachine` has been configured for a
specific class, the log-likelihood (score) that an input sample belongs to the
enrolled class, can be estimated, by first computing the GMM sufficient
statistics of this input sample, and then calling the
-:py:meth:`bob.learn.misc.JFAMachine:forward` on the sufficient statistics.
+:py:meth:`bob.learn.misc.JFAMachine.forward` on the sufficient statistics.
.. doctest::
:options: +NORMALIZE_WHITESPACE
@@ -266,7 +266,7 @@ Once the :py:class:`bob.learn.misc.ISVMachine` has been configured for a
specific class, the log-likelihood (score) that an input sample belongs to the
enrolled class, can be estimated, by first computing the GMM sufficient
statistics of this input sample, and then calling the
-:py:meth:`bob.learn.misc.ISVMachine:forward` on the sufficient statistics.
+:py:meth:`bob.learn.misc.ISVMachine.forward` on the sufficient statistics.
.. doctest::
:options: +NORMALIZE_WHITESPACE
@@ -301,7 +301,7 @@ information about these two matrices. This can be initialized as follows:
Once the :py:class:`bob.learn.misc.IVectorMachine` has been set, the
-extraction of an i-vector :math:`w_ij` can be done in two steps, by first
+extraction of an i-vector :math:`w_{ij}` can be done in two steps, by first
extracting the GMM sufficient statistics, and then estimating the i-vector:
.. doctest::
@@ -364,8 +364,8 @@ K-means
**k-means** [7]_ is a clustering method, which aims to partition a set of
observations into :math:`k` clusters. This is an `unsupervised` technique. As
-for **PCA** [1]_, the training data is passed in a 2D :py:class:`numpy.ndarray`
-container.
+for **PCA** [1]_, which is implemented in the :py:class:`bob.learn.linear.PCATrainer`
+class, the training data is passed in a 2D :py:class:`numpy.ndarray` container.
.. doctest::
:options: +NORMALIZE_WHITESPACE
@@ -738,8 +738,8 @@ separately for each model.
In a verification scenario, there are two possible hypotheses: 1.
:math:`x_{test}` and :math:`x_{enrol}` share the same class. 2.
:math:`x_{test}` and :math:`x_{enrol}` are from different classes. Using the
-methods :py:meth:`bob.learn.misc.PLDAMachine:call()` or
-:py:meth:`bob.learn.misc.PLDAMachine:forward()`, the corresponding
+methods :py:meth:`bob.learn.misc.PLDAMachine.forward` or
+:py:meth:`bob.learn.misc.PLDAMachine.__call__` function, the corresponding
log-likelihood ratio will be computed, which is defined in more formal way by:
:math:`s = \ln(P(x_{test},x_{enrol})) - \ln(P(x_{test})P(x_{enrol}))`
diff --git a/setup.py b/setup.py
index 289c698..0c110b0 100644
--- a/setup.py
+++ b/setup.py
@@ -21,7 +21,7 @@ setup(
name='bob.learn.misc',
version=version,
- description='Bindings for miscelaneous machines and trainers',
+ description='Bindings for miscelaneous machines and trainers of Bob',
url='http://github.com/bioidiap/bob.learn.misc',
license='BSD',
author='Andre Anjos',
@@ -143,6 +143,7 @@ setup(
},
classifiers = [
+ 'Framework :: Bob',
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
--
GitLab