New README and documentation strategy.

.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/

.travis.yml

@@ -6,6 +6,7 @@ matrix:
     env:
     - secure: O8KvS+a9yEOWAVH3Htsj2lrKzu17OP5gOx76sxV46JXBLlLb4WFeOayFu2XRTvuUQI+AqjqiHFIg4qCMFgHxHatkmr1qIZg+AIzL+OozvGgu3W/yPp5+vWchX0H1r9i4VM1UCJ1WlUJHUlNyMYCSPrIw6lwZAh+Dro6aYiSzq1I=
     - secure: PDraLxmhgSDHQJD5fmu2ychRzDO6kCy+9c+lM7vsrj1YlIADo4Y9xSfbWKdbqK1Y3za/6FzD9a7WnJOYLPeD4wpQHRYiyeha32s9kMxORDT7SB8IHqdt8gtxxvV8tqWMYIj49BJM24KJceBwYm2By/vML9hRACn0XIrJRzATXbI=
+    - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
   - python: 3.2
     env:
     - NUMPYSPEC===1.7.1
@@ -15,7 +16,7 @@ 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

README.rst

@@ -2,79 +2,36 @@
 .. Andre Anjos <andre.anjos@idiap.ch>
 .. Fri 13 Dec 2013 12:35:22 CET
 
-.. image:: https://travis-ci.org/bioidiap/bob.learn.linear.svg?branch=master
-   :target: https://travis-ci.org/bioidiap/bob.learn.linear
+.. image:: http://img.shields.io/badge/docs-stable-yellow.png
+   :target: http://pythonhosted.org/bob.learn.linear/index.html
 .. image:: http://img.shields.io/badge/docs-latest-orange.png
    :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.linear/master/index.html
+.. image:: https://travis-ci.org/bioidiap/bob.learn.linear.svg?branch=master
+   :target: https://travis-ci.org/bioidiap/bob.learn.linear
 .. image:: https://coveralls.io/repos/bioidiap/bob.learn.linear/badge.png
    :target: https://coveralls.io/r/bioidiap/bob.learn.linear
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.learn.linear.png
-   :target: https://github.com/bioidiap/bob.learn.linear
+.. image:: https://img.shields.io/badge/github-master-0000c0.png
+   :target: https://github.com/bioidiap/bob.learn.linear/tree/master
 .. image:: http://img.shields.io/pypi/v/bob.learn.linear.png
    :target: https://pypi.python.org/pypi/bob.learn.linear
 .. image:: http://img.shields.io/pypi/dm/bob.learn.linear.png
    :target: https://pypi.python.org/pypi/bob.learn.linear
 
-==============================================================
- Python bindings for bob.machine's LinearMachine and Trainers
-==============================================================
+=====================================
+ Linear Machine and Trainers for Bob
+=====================================
 
-This package contains a set of Pythonic bindings for Bob's LinearMachine and
-Trainers.
+This package contains Bob's Linear Machine and Trainers for it.
 
 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.linear/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.linear/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 latest version of the documentation can be found `here <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.linear/master/index.html>`_.
-
-Otherwise, you can generate the documentation for this package yourself, 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
-
-.. 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.linear
-
-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

bob/learn/linear/lda.cpp

@@ -23,7 +23,7 @@ PyDoc_STRVAR(s_pcatrainer_doc,
 "FisherLDATrainer([use_pinv=False [, strip_to_rank=True]]) -> new FisherLDATrainer\n\
 FisherLDATrainer(other) -> new FisherLDATrainer\n\
 \n\
-Trains a :py:class:`bob.machine.LinearMachine` to perform\n\
+Trains a :py:class:`bob.learn.linear.Machine` to perform\n\
 Fisher's Linear Discriminant Analysis (LDA).\n\
 \n\
 Objects of this class can be initialized in two ways. In the\n\
@@ -344,7 +344,7 @@ elements as classes you want to discriminate.\n\
 .. note::\n\
    \n\
    We set at most\n\
-   :py:meth:`bob.trainer.FisherLDATrainer.output_size`\n\
+   :py:meth:`bob.learn.linear.FisherLDATrainer.output_size`\n\
    eigen-values and vectors on the passed machine. You can\n\
    compress the machine output further using\n\
    :py:meth:`bob.learn.linear.Machine.resize` if necessary.\n\

bob/learn/linear/machine.cpp

@@ -807,7 +807,7 @@ PyDoc_STRVAR(s_load_str, "load");
 PyDoc_STRVAR(s_load_doc,
 "o.load(f) -> None\n\
 \n\
-Loads itself from a :py:class:`bob.io.HDF5File`\n\
+Loads itself from a :py:class:`bob.io.base.HDF5File`\n\
 \n\
 ");
 
@@ -841,7 +841,7 @@ PyDoc_STRVAR(s_save_str, "save");
 PyDoc_STRVAR(s_save_doc,
 "o.save(f) -> None\n\
 \n\
-Saves itself at a :py:class:`bob.io.HDF5File`\n\
+Saves itself at a :py:class:`bob.io.base.HDF5File`\n\
 \n\
 ");
 

bob/learn/linear/pca.cpp

@@ -113,10 +113,10 @@ corresponds to its eigen values.\n\
    Our implementation uses LAPACK's ``dgesdd`` to compute the\n\
    solution to this linear equation.\n\
 \n\
-The corresponding :py:class:`bob.learn.Linear.Machine` and\n\
+The corresponding :py:class:`bob.learn.linear.Machine` and\n\
 returned eigen-values of :math:`\\Sigma`, are pre-sorted in\n\
 descending order (the first eigen-vector - or column - of the\n\
-weight matrix in the :py:class:`bob.learn.Linear.Machine`\n\
+weight matrix in the :py:class:`bob.learn.linear.Machine`\n\
 corresponds to the highest eigen value obtained).\n\
 \n\
 .. note::\n\

buildout.cfg

@@ -19,6 +19,7 @@ develop = src/bob.extension
 ; options for bob.buildout extension
 debug = true
 verbose = true
+newest = false
 
 [sources]
 bob.extension = git https://github.com/bioidiap/bob.extension

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

doc/guide.rst

@@ -58,13 +58,12 @@ in double-precision. Here is how to use a
   array([ 0.55,  0.55])
 
 As was shown in the above example, the way to pass data through a machine is to
-call its :py:meth:`bob.learn.linear.Machine.__call__()` operator.
+call its :py:meth:`bob.learn.linear.Machine.forward` function, for which the :py:meth:`bob.learn.linear.Machine.__call__` funciton is an alias.
 
 The first thing to notice about machines is that they can be stored and
-retrieved in HDF5 files (for more details in manipulating HDF5 files, please
-consult the documentation for :py:mod:`bob.io.base`. To save the before
+retrieved in :py:class:`bob.io.base.HDF5File`. To save the before
 metioned machine to a file, just use the machine's
-:py:meth:`bob.learn.linear.Machine.save`` command. Because several machines
+:py:meth:`bob.learn.linear.Machine.save` command. Because several machines
 can be stored on the same :py:class:`bob.io.base.HDF5File`, we let the user
 open the file and set it up before the machine can write to it:
 

setup.py

@@ -21,7 +21,7 @@ setup(
 
     name='bob.learn.linear',
     version=version,
-    description='Bindings for bob.machine\'s LinearMachine and Trainers',
+    description='Bob\'s Linear Machine and its Trainers',
     url='http://github.com/bioidiap/bob.learn.linear',
     license='BSD',
     author='Andre Anjos',
@@ -94,7 +94,8 @@ setup(
     },
 
     classifiers = [
-      'Development Status :: 3 - Alpha',
+      'Framework :: Bob',
+      'Development Status :: 4 - Beta',
       'Intended Audience :: Developers',
       'License :: OSI Approved :: BSD License',
       'Natural Language :: English',
@@ -103,4 +104,4 @@ setup(
       'Topic :: Software Development :: Libraries :: Python Modules',
     ],
 
-  )
+)