Commit 6ae8e8f5 authored by Manuel Günther's avatar Manuel Günther

New README and documentation strategy.

parent 98563c28
...@@ -2,6 +2,7 @@ ...@@ -2,6 +2,7 @@
*.swp *.swp
*.pyc *.pyc
*.so *.so
*.dylib
bin bin
eggs eggs
parts parts
......
...@@ -6,6 +6,7 @@ matrix: ...@@ -6,6 +6,7 @@ matrix:
env: env:
- secure: F8PfOJ9nGrtZdTcv132jrx5spnzFfpFCSMtea4TLwvotbFc7/gHVEu2UeLktWuVVnL715MSbJ8aXAFR918qwwJsCop0fnPNtgC70nLbYUNWvyOSzvm6JwXA9cYHvAgxYA4Y1folXcz+0bIQqD0MkBM/1yiLivS1kHP3K2jrdWNk= - secure: F8PfOJ9nGrtZdTcv132jrx5spnzFfpFCSMtea4TLwvotbFc7/gHVEu2UeLktWuVVnL715MSbJ8aXAFR918qwwJsCop0fnPNtgC70nLbYUNWvyOSzvm6JwXA9cYHvAgxYA4Y1folXcz+0bIQqD0MkBM/1yiLivS1kHP3K2jrdWNk=
- secure: YAMap+9kNi9om5b4h1leawWrpgkvt1iIv3UVkfp0zTSM9kb1qVjJxWd75IxjbVSGXQ5hoMAgyOzCwOFoa4r3LMf8bBtStZ4zeoaichxEQHr05C5BXgHFDWUnFdpInvODMbfznySdxiLLWQ6kJFldmdFwYizJxcKxSWqL4EQ3Snw= - secure: YAMap+9kNi9om5b4h1leawWrpgkvt1iIv3UVkfp0zTSM9kb1qVjJxWd75IxjbVSGXQ5hoMAgyOzCwOFoa4r3LMf8bBtStZ4zeoaichxEQHr05C5BXgHFDWUnFdpInvODMbfznySdxiLLWQ6kJFldmdFwYizJxcKxSWqL4EQ3Snw=
- BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
- python: 3.2 - python: 3.2
env: env:
- NUMPYSPEC===1.7.1 - NUMPYSPEC===1.7.1
...@@ -15,7 +16,7 @@ matrix: ...@@ -15,7 +16,7 @@ matrix:
before_install: before_install:
- sudo add-apt-repository -y ppa:biometrics/bob - sudo add-apt-repository -y ppa:biometrics/bob
- sudo apt-get update -qq - sudo apt-get update -qq
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libjpeg8-dev libnetpbm10-dev libpng12-dev libtiff4-dev libgif-dev libhdf5-serial-dev - sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libjpeg8-dev libnetpbm10-dev libpng12-dev libtiff4-dev libgif-dev libhdf5-serial-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 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 --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 sphinx nose==1.3.0 jinja2==2.6; fi - if [ -n "${NUMPYSPEC}" ]; then pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel numpy$NUMPYSPEC sphinx nose==1.3.0 jinja2==2.6; fi
......
...@@ -2,14 +2,16 @@ ...@@ -2,14 +2,16 @@
.. Andre Anjos <andre.anjos@idiap.ch> .. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 29 Aug 2013 16:07:57 CEST .. Thu 29 Aug 2013 16:07:57 CEST
.. image:: https://travis-ci.org/bioidiap/bob.io.image.svg?branch=master .. image:: http://img.shields.io/badge/docs-stable-yellow.png
:target: https://travis-ci.org/bioidiap/bob.io.image :target: http://pythonhosted.org/bob.io.image/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png .. image:: http://img.shields.io/badge/docs-latest-orange.png
:target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.image/master/index.html :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.image/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.io.image.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.io.image
.. image:: https://coveralls.io/repos/bioidiap/bob.io.image/badge.png .. image:: https://coveralls.io/repos/bioidiap/bob.io.image/badge.png
:target: https://coveralls.io/r/bioidiap/bob.io.image :target: https://coveralls.io/r/bioidiap/bob.io.image
.. image:: http://img.shields.io/github/tag/bioidiap/bob.io.image.png .. image:: https://img.shields.io/badge/github-master-0000c0.png
:target: https://github.com/bioidiap/bob.io.image :target: https://github.com/bioidiap/bob.io.image/tree/master
.. image:: http://img.shields.io/pypi/v/bob.io.image.png .. image:: http://img.shields.io/pypi/v/bob.io.image.png
:target: https://pypi.python.org/pypi/bob.io.image :target: https://pypi.python.org/pypi/bob.io.image
.. image:: http://img.shields.io/pypi/dm/bob.io.image.png .. image:: http://img.shields.io/pypi/dm/bob.io.image.png
...@@ -19,116 +21,19 @@ ...@@ -19,116 +21,19 @@
Image I/O Support for Bob Image I/O Support for Bob
=========================== ===========================
This package contains no bindings. By importing it, you activate a transparent This packages contains an interface for image IO.
plugin that makes possible reading and writing to image files using By importing this package, you activate a transparent plugin that makes possible reading and writing to image files using :py:mod:`bob.io.base` functionalities.
:py:mod:`bob.io.base` functionality.
Installation 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>`_.
Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap For Bob_ to be able to work properly, some dependent packages are required to be installed.
the package and run test units. Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
External Library Requirements
=============================
To properly install this package, you will need the following C/C++ components
pre-installed:
1. ``bob-io >= 2.0.0a2``
2. ``libtiff-4``
3. ``libpng``
4. ``libjpeg``
5. ``giflib``
6. ``netpbm``
To test for the availability of the libraries listed above, use the command
``pkg-config``::
$ pkg-config --modversion libtiff-4
4.0.2
$ pkg-config --modversion bob-io
2.0.0a3
.. note::
Unfortunately, ``libjpeg``, ``giflib`` and ``netpbm`` do **not** offer
``pkg-config`` files as of this time. Detection is based on an algorithm
implemented inside ``setup.py``. There are no version requirements on these
libraries. Any version will work.
If these libraries are installed in non-standard paths on your system, make
sure to set ``prefixes`` variable on your buildout.
If any of the components is not installed on paths accessible by
``pkg-config``, you have two options:
1. Set the environment variable ``PKG_CONFIG_PATH`` so that ``.pc`` files for
each of those distributions can be properly located (see ``man pkg-config``
for details);
2. If you are using ``zc.buildout`` to setup your working environment, you can
use the buildout variable ``prefixes`` to define the path to the
installation area for your external packages.
Documentation Documentation
------------- -------------
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.io.image/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.image/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.io.image/master/index.html>`_. .. _bob: https://www.idiap.ch/software/bob
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.
Usage
-----
In order to enable support for Matlab(R) file reading and writing in your
application, make sure to import this module, before calling
:py:func:`bob.io.base.open` or similar::
>>> import bob.io.base
>>> import bob.io.image
>>> bob.io.base.open('myfile.mat', 'r')
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.io.image
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.
...@@ -249,36 +249,10 @@ autoclass_content = 'both' ...@@ -249,36 +249,10 @@ autoclass_content = 'both'
autodoc_member_order = 'bysource' autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance'] 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: # For inter-documentation mapping:
intersphinx_mapping = { from bob.extension.utils import link_documentation
'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None, intersphinx_mapping = link_documentation()
numpy_manual: None,
}
def setup(app): def setup(app):
pass pass
...@@ -19,7 +19,7 @@ ...@@ -19,7 +19,7 @@
============ ============
By importing this package, you can use |project| native array reading and By importing this package, you can use |project| native array reading and
writing routines to load and save files using various image formats. writing routines to load and save files using various image formats, using the simple plug-in technology for :py:mod:`bob.io.base`, i.e., :py:func:`bob.io.base.load` and :py:func:`bob.io.base.save`.
.. code-block:: python .. code-block:: python
...@@ -28,14 +28,15 @@ writing routines to load and save files using various image formats. ...@@ -28,14 +28,15 @@ writing routines to load and save files using various image formats.
>> x = bob.io.base.load('myfile.jpg') >> x = bob.io.base.load('myfile.jpg')
In the following example, an image generated randomly using the method `NumPy` In the following example, an image generated randomly using the method `NumPy`
:py:meth:`numpy.random.random_integers`, is saved in JPEG format. The image :py:func:`numpy.random.random_integers`, is saved in lossless PNG format. The image
must be of type ``uint8`` or ``uint16``: must be of type ``uint8`` or ``uint16``:
.. doctest:: .. doctest::
>>> my_image = numpy.random.random_integers(0,255,(3,256,256)) >>> my_image = numpy.random.random_integers(0,255,(3,256,256))
>>> bob.io.base.save(my_image.astype('uint8'), 'testimage.jpg') # saving the image in jpeg format >>> bob.io.base.save(my_image.astype('uint8'), 'testimage.png') # saving the image in png format
>>> my_image_copy = bob.io.base.load('testimage.jpg') >>> my_image_copy = bob.io.base.load('testimage.png')
>>> assert (my_image_copy == my_image).all()
The loaded image files can be 3D arrays (for RGB format) or 2D arrays (for The loaded image files can be 3D arrays (for RGB format) or 2D arrays (for
greyscale) of type ``uint8`` or ``uint16``. greyscale) of type ``uint8`` or ``uint16``.
......
...@@ -475,7 +475,8 @@ setup( ...@@ -475,7 +475,8 @@ setup(
}, },
classifiers = [ classifiers = [
'Development Status :: 3 - Alpha', 'Framework :: Bob',
'Development Status :: 4 - Beta',
'Intended Audience :: Developers', 'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License', 'License :: OSI Approved :: BSD License',
'Natural Language :: English', 'Natural Language :: English',
......
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