From 930c02145c9659c353d6b7e6a5ccfffe6dde6fb0 Mon Sep 17 00:00:00 2001 From: Manuel Guenther <manuel.guenther@idiap.ch> Date: Tue, 28 Oct 2014 15:11:24 +0100 Subject: [PATCH] New README and documentation strategy. --- .gitignore | 2 -- .travis.yml | 3 ++- README.rst | 73 ++++++++++----------------------------------------- doc/conf.py | 6 ++++- doc/guide.rst | 3 ++- setup.py | 9 ++++--- 6 files changed, 28 insertions(+), 68 deletions(-) diff --git a/.gitignore b/.gitignore index 582c473..dae95ef 100644 --- a/.gitignore +++ b/.gitignore @@ -2,9 +2,7 @@ *.swp *.pyc *.so -*.so.* *.dylib -CMakeLists.txt bin eggs parts diff --git a/.travis.yml b/.travis.yml index 5cc777f..423d82d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -6,6 +6,7 @@ matrix: env: - secure: MC0lSIqOFXAuE4XzlRegncweAu+CV61QJL6mzuWHKUGKgZyjOeQOaMGkR66CmIeeEtt6xXSVh2944w9D8/mUg5Xw8e9cxz9eZIE+MdreYoZEly83zI+fai7/6mjPiz9QIDrEaY9sYd51kubTpE8/9DTrbljl/WjR4O8rdqv+gmc= - secure: cWqM2TBcrRco5W38Cp5z2/662b9CrOsy9SA7tm+g35XqphHjDRpkOL9/jUpEI7D2l4NF1V8EqMuswPyK7nzABd2tVrRsEuiM5W71ZkgS7vASqkHIleminNfRhAf8uJeGeYdj1IbUqPITZhdm1yDqSTTrEnCD/798k8Nf8tY5L/c= + - 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 +- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-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 diff --git a/README.rst b/README.rst index 6ef9915..443754d 100644 --- a/README.rst +++ b/README.rst @@ -2,79 +2,34 @@ .. Andre Anjos <andre.anjos@idiap.ch> .. Thu 29 Aug 2013 16:07:57 CEST -.. image:: https://travis-ci.org/bioidiap/bob.core.svg?branch=master - :target: https://travis-ci.org/bioidiap/bob.core +.. image:: http://img.shields.io/badge/docs-stable-yellow.png + :target: http://pythonhosted.org/bob.core/index.html .. image:: http://img.shields.io/badge/docs-latest-orange.png :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.core/master/index.html +.. image:: https://travis-ci.org/bioidiap/bob.core.svg?branch=master + :target: https://travis-ci.org/bioidiap/bob.core .. image:: https://coveralls.io/repos/bioidiap/bob.core/badge.png :target: https://coveralls.io/r/bioidiap/bob.core -.. image:: http://img.shields.io/github/tag/bioidiap/bob.core.png - :target: https://github.com/bioidiap/bob.core .. image:: http://img.shields.io/pypi/v/bob.core.png :target: https://pypi.python.org/pypi/bob.core .. image:: http://img.shields.io/pypi/dm/bob.core.png :target: https://pypi.python.org/pypi/bob.core -============================== - Python bindings for bob.core -============================== +==================== + Bob's core package +==================== -This package contains a set of Pythonic bindings for Bob's core packages and -functionality. +This package contains a set of Pythonic bindings for Bob's core package and functionality like logging, random number generation and array type conversion. 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.core/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.core/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.core/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.core - -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/doc/conf.py b/doc/conf.py index 960d1c2..9e1a256 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -278,7 +278,11 @@ numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version 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.update(link_documentation()) + def setup(app): pass diff --git a/doc/guide.rst b/doc/guide.rst index 1fe6027..63835ae 100644 --- a/doc/guide.rst +++ b/doc/guide.rst @@ -14,8 +14,9 @@ Array Conversion ---------------- + The function :py:func:`bob.core.convert` allows you to convert objects of type -:py:class:`numpy.ndarray` between different types, with range compression or +:py:class:`numpy.ndarray` or :py:class:`bob.blitz.array` between different types, with range compression or decompression. For example, here we demonstrate a conversion using default ranges. In this type of conversion, our implementation will assume that the source array contains values within the range of ``uint8_t`` numbers and will diff --git a/setup.py b/setup.py index d960ba5..5e11401 100644 --- a/setup.py +++ b/setup.py @@ -30,7 +30,7 @@ setup( namespace_packages=[ "bob", - ], + ], setup_requires = build_requires, install_requires = build_requires, @@ -57,7 +57,7 @@ setup( Extension("bob.core._convert", [ "bob/core/convert.cpp", - ], + ], version = version, packages = packages, ), @@ -65,7 +65,7 @@ setup( Extension("bob.core._logging", [ "bob/core/logging.cpp", - ], + ], version = version, packages = packages, boost_modules = ['system', 'iostreams', 'filesystem'], @@ -93,6 +93,7 @@ setup( }, classifiers = [ + 'Framework :: Bob', 'Development Status :: 3 - Alpha', 'Intended Audience :: Developers', 'License :: OSI Approved :: BSD License', @@ -102,4 +103,4 @@ setup( 'Topic :: Software Development :: Libraries :: Python Modules', ], - ) +) -- GitLab