Commit 092cfc2e authored by Manuel Günther's avatar Manuel Günther

New README and documentation strategy.

parent c7361ed8
......@@ -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/
......@@ -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
......
......@@ -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
......@@ -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\
......
......@@ -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\
");
......
......@@ -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\
......
......@@ -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
......
......@@ -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
......@@ -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:
......
......@@ -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',
],
)
)
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment