Commit 300e69ca authored by Manuel Günther's avatar Manuel Günther

New README and documentation strategy.

parent 0f0e49aa
......@@ -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: JnEd9VsJI6Kff86rvQ3RPxoMSTef8osnBFfmbbp6ZATs4JyndGRLdF4JPBNKPkaQpno+miEXNaBQdg+nU3e/pi8GngicvL6EIHYXQpw6Wpz/YKvEOexk16Lm4WsVNZFZTrVF3+gepMjDZbCfyZLwENxGdjz1Beub7XGfUZ8rcj4=
- secure: K41vqTkHkqWrpsB9Rnfmt9M2+lFKFAfRpmRRbHGf7MIKjS1rZJiM91mDsVElfbzDHzCcb6jN5I09LN5omrA8q56d8D3otZrPNwgfGVIoi1F2tRtekva16PTABWFPruVGApZsFREIQzV7CneaXRq37TBKhoTeTGsTZF8ZZy8db3A=
- 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 libsvm-dev
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev libsvm-dev texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
- if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq libatlas-dev libatlas-base-dev liblapack-dev 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,102 +2,52 @@
.. Andre Anjos <andre.anjos@idiap.ch>
.. Fri 13 Dec 2013 12:35:22 CET
.. image:: https://travis-ci.org/bioidiap/bob.learn.libsvm.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.learn.libsvm
.. image:: http://img.shields.io/badge/docs-stable-yellow.png
:target: http://pythonhosted.org/bob.learn.libsvm/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
:target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.libsvm/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.learn.libsvm.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.learn.libsvm
.. image:: https://coveralls.io/repos/bioidiap/bob.learn.libsvm/badge.png
:target: https://coveralls.io/r/bioidiap/bob.learn.libsvm
.. image:: http://img.shields.io/github/tag/bioidiap/bob.learn.libsvm.png
:target: https://github.com/bioidiap/bob.learn.libsvm
.. image:: https://img.shields.io/badge/github-master-0000c0.png
:target: https://github.com/bioidiap/bob.learn.libsvm/tree/master
.. image:: http://img.shields.io/pypi/v/bob.learn.libsvm.png
:target: https://pypi.python.org/pypi/bob.learn.libsvm
.. image:: http://img.shields.io/pypi/dm/bob.learn.libsvm.png
:target: https://pypi.python.org/pypi/bob.learn.libsvm
================================
Bob-Python bindings for LIBSVM
================================
==================================
Bob's Python bindings for LIBSVM
==================================
This package contains a set of Pythonic bindings for LIBSVM.
External Software Requirements
------------------------------
This package requires you have ``LIBSVM`` installed on your system. If
``LIBSVM`` is installed on a standard location, this package will find it
automatically. You can just skip to the installation instructions.
This package requires you have ``LIBSVM`` installed on your system.
If ``LIBSVM`` is installed on a standard location, this package will find it automatically.
You can just skip to the installation instructions.
In case you have installed ``LIBSVM`` on a non-standard location (e.g. your
home directory), then you can specify the path to the root of that installation
using the environment variable ``BOB_PREFIX_PATH``, **before** building and
installing the package. For example, if ``BOB_PREFIX_PATH`` is set to
``/home/user/libsvm-3.12``, then we will search for the header file ``svm.h``
in ``/home/user/libsvm-3.12/include`` and expect that the library file file is
found under ``/home/user/libsvm-3.12/lib``.
In case you have installed ``LIBSVM`` on a non-standard location (e.g. your home directory), then you can specify the path to the root of that installation using the environment variable ``BOB_PREFIX_PATH``, **before** building and installing the package.
For example, if ``BOB_PREFIX_PATH`` is set to ``/home/user/libsvm-3.12``, then we will search for the header file ``svm.h`` in ``/home/user/libsvm-3.12/include`` and expect that the library file file is found under ``/home/user/libsvm-3.12/lib``.
If you are installing this package via ``pip`` for example, just set the
environment variable like this::
If you are installing this package via ``pip`` for example, just set the environment variable like this::
$ BOB_PREFIX_PATH=/home/user/libsvm-3.12 pip install bob.learn.libsvm
If you are installing this package via ``zc.buildout``, we recommend you use
our `bob.buildout <http://pypi.python.org/pypi/bob.buildout>`_ extension and
set the ``[environ]`` section to define ``BOB_PREFIX_PATH``.
If you are installing this package via ``zc.buildout``, we recommend you use our `bob.buildout <http://pypi.python.org/pypi/bob.buildout>`_ extension and set the ``[environ]`` section to define ``BOB_PREFIX_PATH``.
Installation
------------
Install it through normal means, via ``pip`` or use ``zc.buildout`` to
bootstrap the package itself 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.libsvm/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.learn.libsvm/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.libsvm/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.libsvm
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
......@@ -41,7 +41,7 @@ LIBSVM uses a sparse format.\n\
Upon construction, objects of this class will inspect the input\n\
file so that the maximum sample size is computed. Once that job\n\
is performed, you can read the data in your own pace using the\n\
:py:meth:`File.read` method.\n\
:py:meth:`read` method.\n\
\n\
This class is made available to you so you can input original\n\
LIBSVM files and convert them to another better supported\n\
......@@ -229,7 +229,7 @@ PyDoc_STRVAR(s_good_doc,
Returns if the file is in a good state for readout.\n\
It is ``True`` if the current file it has neither the\n\
``eof``, ``fail`` or ``bad`` bits set, whic means that\n\
next :py:meth:`File.read` operation may succeed.\n\
next :py:meth:`read` operation may succeed.\n\
");
PyObject* PyBobLearnLibsvmFile_good(PyBobLearnLibsvmFileObject* self) {
......@@ -254,7 +254,7 @@ PyDoc_STRVAR(s_fail_doc,
Returns ``True`` if the file has a ``fail`` condition or\n\
``bad`` bit sets. It means the read operation has found a\n\
critical condition and you can no longer proceed in reading\n\
from the file. Note this is not the same as :py:meth:`File.eof`\n\
from the file. Note this is not the same as :py:meth:`eof`\n\
which informs if the file has ended, but no errors were found\n\
during the read operations.\n\
");
......@@ -279,7 +279,7 @@ PyDoc_STRVAR(s_eof_doc,
"o.eof() -> bool\n\
\n\
Returns ``True`` if the file has reached its end. To start\n\
reading from the file again, you must call :py:meth:`File.reset`\n\
reading from the file again, you must call :py:meth:`reset`\n\
before another read operation may succeed.\n\
");
......@@ -305,13 +305,13 @@ PyDoc_STRVAR(s_read_doc,
Reads a single line from the file and returns a tuple\n\
containing the label and a numpy array of ``float64``\n\
elements. The :py:class:`numpy.ndarray` has a shape\n\
as defined by the :py:attr:`File.shape` attribute of\n\
as defined by the :py:attr:`shape` attribute of\n\
the current file. If the file has finished, this method\n\
returns ``None`` instead.\n\
\n\
If the output array ``values`` is provided, it must be a\n\
64-bit float array with a shape matching the file shape as\n\
defined by :py:attr:`File.shape`. Providing an output\n\
defined by :py:attr:`shape`. Providing an output\n\
array avoids constant memory re-allocation.\n\
\n\
");
......@@ -391,11 +391,11 @@ Reads all contents of the file into the output arrays\n\
The array ``labels``, if provided, must be a 1D\n\
:py:class:`numpy.ndarray` with data type ``int64``,\n\
containing as many positions as entries in the file, as\n\
returned by the attribute :py:attr:`File.samples`. The\n\
returned by the attribute :py:attr:`samples`. The\n\
array ``values``, if provided, must be a 2D array with\n\
data type ``float64``, as many rows as entries in the\n\
file and as many columns as features in each entry, as\n\
defined by the attribute :py:attr:`File.shape`.\n\
defined by the attribute :py:attr:`shape`.\n\
\n\
If the output arrays ``labels`` and/or ``values`` are not\n\
provided, they will be allocated internally and returned.\n\
......@@ -404,7 +404,7 @@ provided, they will be allocated internally and returned.\n\
\n\
This method is intended to be used for reading the\n\
whole contents of the input file. The file will be\n\
reset as by calling :py:meth:`File.reset` before the\n\
reset as by calling :py:meth:`reset` before the\n\
readout starts.\n\
\n\
");
......
......@@ -932,11 +932,11 @@ PyDoc_STRVAR(s_save_doc,
o.save(hdf5file) -> None\n\
\n\
Saves itself at a LIBSVM model file or into a\n\
:py:class:`bob.io.HDF5File`. Saving the SVM into an\n\
:py:class:`bob.io.HDF5File` object, has the advantage of saving\n\
:py:class:`bob.io.base.HDF5File`. Saving the SVM into an\n\
:py:class:`bob.io.base.HDF5File` object, has the advantage of saving\n\
input normalization options together with the machine, which are\n\
automatically reloaded when you re-initialize it from the same\n\
:py:class:`HDF5File`.\n\
:py:class:`bob.io.base.HDF5File`.\n\
");
static PyObject* PyBobLearnLibsvmMachine_Save
......
......@@ -17,6 +17,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
......
......@@ -293,7 +293,7 @@ objects is described in this section.
.. note::
This method is typically only used by the respective
:cpp:class`bob::learn::libsvm::Trainer` as it requires the creation of
:cpp:class:`bob::learn::libsvm::Trainer` as it requires the creation of
the object ``svm_model``. You can still make use of it if you decide
to implement the model instantiation yourself.
......
......@@ -250,41 +250,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,
}
# For Breathe
breathe_projects = {
'cxx': 'doc/xml',
}
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation()
def setup(app):
pass
......@@ -157,7 +157,7 @@ setup(
name='bob.learn.libsvm',
version=version,
description='Bob bindings to libsvm',
description='Bob\'s Python bindings to LIBSVM',
url='http://github.com/bioidiap/bob.learn.libsvm',
license='BSD',
author='Andre Anjos',
......@@ -235,13 +235,14 @@ setup(
},
classifiers = [
'Development Status :: 3 - Alpha',
'Framework :: Bob',
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Natural Language :: English',
'Programming Language :: Python',
'Programming Language :: Python :: 3',
'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