From 18197345696ea62ea6e5104c48b9ddc0ae9c567f Mon Sep 17 00:00:00 2001
From: Manuel Guenther <manuel.guenther@idiap.ch>
Date: Tue, 28 Oct 2014 17:43:45 +0100
Subject: [PATCH] New README and documentation strategy.

---
 .gitignore     |  2 +-
 .travis.yml    |  3 ++-
 README.rst     | 73 ++++++++++----------------------------------------
 doc/conf.py    | 32 +++-------------------
 doc/guide.rst  |  6 ++---
 doc/py_api.rst |  2 +-
 setup.py       |  5 ++--
 7 files changed, 27 insertions(+), 96 deletions(-)

diff --git a/.gitignore b/.gitignore
index 9f9c80d..dae95ef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,7 @@
 *.swp
 *.pyc
 *.so
+*.dylib
 bin
 eggs
 parts
@@ -16,4 +17,3 @@ dist
 build
 *.egg
 src/
-opsnr.stt
diff --git a/.travis.yml b/.travis.yml
index 75d240e..5d2919a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -6,6 +6,7 @@ matrix:
     env:
     - secure: U6PO13Ek4WGWqkx1g9nearxLiK9QEOp0/YcncDGtK1uTjH4poEfL4+Zdqdmusgz0ZPzEbpNdDjrVkPdzlHfMCLiD7b1F0ZXwZn8gZaQRljCFVN4gRxHHUSDuhqMCfByJe2dAai7G+NP7k2c4j+kjMMNt0L8Sg9kxPjk99ZH0EL4=
     - secure: SPjDIc4Qs4FsnCUyHbsYKj8+7FmltTrFfoRBEqbYvSC6onRjfkauJEFSBkO2sTv/usa5AcKmCBjfMiqSya2/eSjJzti7d1AWHrtIe8CsU4/KtJkCT/3Y72HJk35CRpUyp/Pd3dhASjrAvI7aByU60EvRfxcwtNJEumwx0bM+OE8=
+    - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
   - python: 3.2
     env:
     - NUMPYSPEC===1.8.0
@@ -15,7 +16,7 @@ matrix:
 before_install:
 - sudo add-apt-repository -y ppa:biometrics/bob
 - sudo apt-get update -qq
-- sudo apt-get install --force-yes libboost-all-dev libblitz1-dev libatlas-dev libatlas-base-dev liblapack-dev libhdf5-serial-dev
+- sudo apt-get install --force-yes libboost-all-dev libblitz1-dev libatlas-dev libatlas-base-dev liblapack-dev libhdf5-serial-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
diff --git a/README.rst b/README.rst
index 583271c..02d38ad 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.measure.svg?branch=master
-   :target: https://travis-ci.org/bioidiap/bob.measure
+.. image:: http://img.shields.io/badge/docs-stable-yellow.png
+   :target: http://pythonhosted.org/bob.measure/index.html
 .. image:: http://img.shields.io/badge/docs-latest-orange.png
    :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.measure/master/index.html
+.. image:: https://travis-ci.org/bioidiap/bob.measure.svg?branch=master
+   :target: https://travis-ci.org/bioidiap/bob.measure
 .. image:: https://coveralls.io/repos/bioidiap/bob.measure/badge.png
    :target: https://coveralls.io/r/bioidiap/bob.measure
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.measure.png
-   :target: https://github.com/bioidiap/bob.measure
 .. image:: http://img.shields.io/pypi/v/bob.measure.png
    :target: https://pypi.python.org/pypi/bob.measure
 .. image:: http://img.shields.io/pypi/dm/bob.measure.png
    :target: https://pypi.python.org/pypi/bob.measure
 
-=================================
- Python bindings for bob.measure
-=================================
+=======================================
+ Experiment Evaluation Metrics for Bob
+=======================================
 
-This package contains a set of Pythonic bindings for Bob's measure packages and
-functionality.
+This package contains Bob's measure packages and functionality.
 
 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.measure/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.measure/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.measure/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.measure
-
-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 ae15b5c..11b2f33 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -250,36 +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,
-  }
+from bob.extension.utils import link_documentation
+intersphinx_mapping = link_documentation()
+
 
 def setup(app):
   pass
diff --git a/doc/guide.rst b/doc/guide.rst
index e64e8c8..ed59b71 100644
--- a/doc/guide.rst
+++ b/doc/guide.rst
@@ -255,7 +255,7 @@ This will produce an image like the following one:
   If you wish to reset axis zooming, you must use the Gaussian scale rather
   than the visual marks showed at the plot, which are just there for
   displaying purposes. The real axis scale is based on the
-  ``bob.measure.ppndf()`` method. For example, if you wish to set the x and y
+  :py:func:`bob.measure.ppndf` method. For example, if you wish to set the x and y
   axis to display data between 1% and 40% here is the recipe:
 
   .. doctest::
@@ -315,8 +315,8 @@ Full applications
 We do provide a few scripts that can be used to quickly evaluate a set of
 scores. We present these scripts in this section. The scripts take as input
 either a 4-column or 5-column data format as specified in the documentation of
-:py:mod:`bob.measure.load.four_column` or
-:py:mod:`bob.measure.load.five_column`.
+:py:func:`bob.measure.load.four_column` or
+:py:func:`bob.measure.load.five_column`.
 
 To calculate the threshold using a certain criterion (EER, min.HTER or weighted
 Error Rate) on a set, after setting up |project|, just do:
diff --git a/doc/py_api.rst b/doc/py_api.rst
index 125a671..b7b2cd7 100644
--- a/doc/py_api.rst
+++ b/doc/py_api.rst
@@ -6,7 +6,7 @@
  Python API
 ============
 
-This section includes information for using the pure Python API of ``bob::measure``.
+This section includes information for using the Python API of :py:mod:`bob.measure`.
 
 
 Measurement
diff --git a/setup.py b/setup.py
index df860d4..6d3adbc 100644
--- a/setup.py
+++ b/setup.py
@@ -20,7 +20,7 @@ setup(
 
     name='bob.measure',
     version=version,
-    description='Bindings for bob.measure',
+    description='Bob\'s evalution metrics',
     url='http://github.com/bioidiap/bob.measure',
     license='BSD',
     author='Andre Anjos',
@@ -74,7 +74,8 @@ setup(
     },
 
     classifiers = [
-      'Development Status :: 3 - Alpha',
+      'Framework :: Bob',
+      'Development Status :: 4 - Beta',
       'Intended Audience :: Developers',
       'License :: OSI Approved :: BSD License',
       'Natural Language :: English',
-- 
GitLab