New README and documentation strategy.

942ac1ae · Manuel Günther · 5fda59bb · 942ac1ae · 942ac1ae · 942ac1ae
Commit 942ac1ae authored 10 years ago by Manuel Günther
--- a/.gitignore
+++ b/.gitignore
 *~
 *.swp
 *.pyc
+*.so
+*.dylib
 bin
 eggs
 parts
@@ -10,11 +12,8 @@ parts
 develop-eggs
 sphinx
 dist
-.project
+.nfs*
-.pydevproject
+.gdb_history
 build
-*.so
+*.egg
 src/
-xbob.extension*.egg
-.gdb_history
-core
--- a/.travis.yml
+++ b/.travis.yml
@@ -6,6 +6,7 @@ matrix:
    env:
    - secure: QSqodxRXJWkKhD1IKFNe1fx/ICpTVlsxgg44FRugrUnInYeWPzmQhQKnmhnCVwlRzYvrCbA5tyC2pZFML4hNBQYgN3gYJxxJR3fpJ9ZSb4xVUD/3LW5iMUzDloEA0/SyT2++W6NAUy85VwjbVeAg4yWBbCeCfFWb6LQUPENO/I8=
    - secure: E1oP5OQ9+keu/GdxV7ju3FZgQBXBvVp0EIq1ge5spsb4ZbZmrcTCzb2hawSo0AHv/ECVYBnM3KcA2TPu6ZcYN0u1oAHM0nojSDllOc7/s1IhRxI/c7RZGTWAhfCklgpAOhdxq6DKIYoJUlq/gLiGIXYGa9jTF27uyEGAm3vnLv0=
+    - BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
  - python: 3.2
    env:
    - NUMPYSPEC===1.8.0
@@ -15,13 +16,13 @@ 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
+- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libhdf5-serial-dev texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
 - sudo apt-get install -qq --force-yes libjpeg8-dev libnetpbm10-dev libpng12-dev libtiff4-dev libgif-dev
 - sudo apt-get install -qq --force-yes python-opencv libcv-dev libcvaux-dev libopencv-dev
 - if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq --force-yes 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 matplotlib==1.3.0 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; fi
- pip install cpp-coveralls
+- pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel matplotlib==1.3.0 sphinx nose==1.3.0 jinja2==2.6 cpp-coveralls setuptools==7.0
 install:
 - python bootstrap.py
 - CFLAGS=-coverage ./bin/buildout

--- a/README.rst
+++ b/README.rst
@@ -2,14 +2,16 @@
 .. Andre Anjos <andre.anjos@idiap.ch>
 .. Thu 17 Apr 16:59:12 2014 CEST
-.. image:: https://travis-ci.org/bioidiap/bob.ip.flandmark.svg?branch=master
+.. image:: http://img.shields.io/badge/docs-stable-yellow.png
-   :target: https://travis-ci.org/bioidiap/bob.ip.flandmark
+   :target: http://pythonhosted.org/bob.ip.flandmark/index.html
 .. image:: http://img.shields.io/badge/docs-latest-orange.png
   :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.ip.flandmark/master/index.html
+.. image:: https://travis-ci.org/bioidiap/bob.ip.flandmark.svg?branch=master
+   :target: https://travis-ci.org/bioidiap/bob.ip.flandmark
 .. image:: https://coveralls.io/repos/bioidiap/bob.ip.flandmark/badge.png
   :target: https://coveralls.io/r/bioidiap/bob.ip.flandmark
-.. image:: http://img.shields.io/github/tag/bioidiap/bob.ip.flandmark.png
+.. image:: https://img.shields.io/badge/github-master-0000c0.png
-   :target: https://github.com/bioidiap/bob.ip.flandmark
+   :target: https://github.com/bioidiap/bob.ip.flandmark/tree/master
 .. image:: http://img.shields.io/pypi/v/bob.ip.flandmark.png
   :target: https://pypi.python.org/pypi/bob.ip.flandmark
 .. image:: http://img.shields.io/pypi/dm/bob.ip.flandmark.png
@@ -19,13 +21,11 @@
 Python Bindings to Flandmark
 ==============================
-This package is a simple Python wrapper to the (rather quick) open-source
+This package is a simple Python wrapper to the (rather quick) open-source facial landmark detector Flandmark_, **version 1.0.7** (or the github state as of 10/february/2013).
-facial landmark detector `Flandmark`_, **version 1.0.7** (or the github state
+If you use this package, the author asks you to cite the following paper::
-as of 10/february/2013). If you use this package, the author asks you to cite
-the following paper::
  @inproceedings{Uricar-Franc-Hlavac-VISAPP-2012,
-    author =      {U{\v{r}}i{\v{c}}{\'{a}}{\v{r}}, Michal and Franc, Vojt{\v{e}}ch and Hlav{\'{a}}{\v{c}}, V{\'{a}}clav},
+    author =      {U\v{r}i\v{c}\'a\v{r}, Michal and Franc, Vojt\v{e}ch and Hlav\'a\v{c}, V\'{a}clav},
    title =       {Detector of Facial Landmarks Learned by the Structured Output {SVM}},
    year =        {2012},
    pages =       {547-556},
@@ -47,11 +47,10 @@ the following paper::
    www = {http://www.visapp.visigrapp.org},
  }
-You should also cite `Bob`_, as a core framework, in which these bindings are
+You should also cite `Bob`_, as a core framework, in which these bindings are based on::
-based on::
  @inproceedings{Anjos_ACMMM_2012,
-    author = {A. Anjos AND L. El Shafey AND R. Wallace AND M. G\"unther AND C. McCool AND S. Marcel},
+    author = {Anjos, Andr\'e AND El Shafey, Laurent AND Wallace, Roy AND G\"unther, Manuel AND McCool, Christopher AND Marcel, S\'ebastien},
    title = {Bob: a free signal processing and machine learning toolbox for researchers},
    year = {2012},
    month = oct,
@@ -62,61 +61,15 @@ based on::
 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.
 Documentation
 -------------
+For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.ip.flandmark/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.ip.flandmark/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.ip.flandmark/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.ip.flandmark
-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.
-.. Place your references here:
-.. _flandmark: http://cmp.felk.cvut.cz/~uricamic/flandmark/index.php
 .. _bob: https://www.idiap.ch/software/bob
+.. _flandmark: http://cmp.felk.cvut.cz/~uricamic/flandmark/index.php
--- a/buildout.cfg
+++ b/buildout.cfg
@@ -20,6 +20,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

--- a/doc/conf.py
+++ b/doc/conf.py
@@ -244,41 +244,16 @@ man_pages = [
    ('index', 'bob_ip_flandmark', u'Python bindings to Flandmark frontal-face keypoint localizer', [u'Idiap Research Institute'], 1)
 ]
 # Default processing flags for sphinx
 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 = {
+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):
  pass
--- a/doc/guide.rst
+++ b/doc/guide.rst
@@ -13,11 +13,8 @@
 Users Guide
 =============
-Flandmark detects 8 coordinates of important keypoints in **frontal** human
+:py:class:`bob.ip.base.Flandmark` detects 8 coordinates of important keypoints in **frontal** human faces.
-faces. To properly work, the keypoint localizer requires the input of an image
+To properly work, the keypoint localizer requires the input of an image (of type ``uint8``, gray-scaled) and of a bounding box describing a rectangle where the face is supposed to be located in the image (see :py:meth:`bob.ip.flandmark.Flandmark.locate`).
-(of type ``uint8``, gray-scaled) and of a bounding box describing a rectangle
-where the face is supposed to be located in the image (see
-:py:class:`bob.ip.flandmark.Flandmark.locate`).
 The keypoints returned are, in this order:
@@ -50,26 +47,22 @@ The keypoints returned are, in this order:
 [7]
  Nose
-Each point is returned as tuple defining the pixel positions in the form
+Each point is returned as tuple defining the pixel positions in the form ``(y, x)``.
-``(y, x)``.
-The input bounding box describes the rectangle coordinates using 4 values:
+The input bounding box describes the rectangle coordinates using 4 values: ``(y, x, height, width)``.
-``(y, x, height, width)``. Square bounding boxes, i.e. when ``height ==
+Square bounding boxes, i.e. when ``height == width``, will give best results.
-width``, will give best results.
-If you don't know the bounding box coordinates of faces on the provided image,
+If you don't know the bounding box coordinates of faces on the provided image, you will need to either manually annotate them or use an automatic face detector.
-you will need to either manually annotate them or use an automatic face
+OpenCV_, if compiled with Python support, provides an easy to use frontal face detector.
-detector. OpenCV_, if compiled with Python support, provides an easy to use
+The code below shall detect most frontal faces in a provided (gray-scaled) image:
-frontal face detector. The code below shall detect most frontal faces in a
-provided (gray-scaled) image:
 .. doctest::
   :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
-   >>> from bob.io.base import load
+   >>> import bob.io.base
   >>> import bob.io.image
-   >>> from bob.ip.color import rgb_to_gray
+   >>> import bob.ip.color
-   >>> lena_gray = rgb_to_gray(load(get_file('lena.jpg')))
+   >>> lena_gray = bob.ip.color.rgb_to_gray(bob.io.base.load(get_file('lena.jpg')))
   >>> try:
   ...   from cv2 import CascadeClassifier
   ...   cc = CascadeClassifier(get_file('haarcascade_frontalface_alt.xml'))
@@ -79,13 +72,15 @@ provided (gray-scaled) image:
   >>> print(face_bbxs)
   [[...]]
-The function ``detectMultiScale`` returns OpenCV_ rectangles as 2D
+.. note::
-:py:class:`numpy.ndarray`'s. Each row corresponds to a detected face at the
+   To enable the :py:func:`bob.io.base.load` function to load images, :ref:`bob.io.image <bob.io.image>` must be imported, see :ref:`bob.io.image`.
-input image. Notice the format of each bounding box differs from that of Bob_.
+The function ``detectMultiScale`` returns OpenCV_ rectangles as 2D :py:class:`numpy.ndarray`\s.
+Each row corresponds to a detected face at the input image.
+Notice the format of each bounding box differs from that of Bob_.
 Their format is ``(x, y, width, height)``.
-Once in possession of bounding boxes for the provided (gray-scaled) image, you
+Once in possession of bounding boxes for the provided (gray-scaled) image, you can find the keypoints in the following way:
-can find the keypoints in the following way:
 .. doctest::
   :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
@@ -97,8 +92,8 @@ can find the keypoints in the following way:
   >>> keypoints
   array([[...]])
-You can use the package ``bob.ip.draw`` to draw the rectangles and keypoints
+You can use the package :ref:`bob.ip.draw <bob.ip.draw>` to draw the rectangles and key-points on the target image.
-on the target image. A complete script would be something like:
+A complete script would be something like:
 .. plot:: plot/show_lena.py
   :include-source: True

--- a/doc/index.rst
+++ b/doc/index.rst
@@ -4,6 +4,8 @@
 ..
 .. Copyright (C) 2011-2014 Idiap Research Institute, Martigny, Switzerland
+.. _bob.ip.flandmark:
 =======================================================================
 Python Bindings to the Flandmark Keypoint Localizer for Frontal Faces
 =======================================================================
@@ -12,12 +14,14 @@
 This package is a simple Python wrapper to the (rather quick) open-source
-facial landmark detector `Flandmark`_, **version 1.0.7** (or the github state
+facial landmark detector Flandmark_, **version 1.0.7** (or the github state
 as of 10/february/2013).  If you use this package, the author asks you to cite
-the following paper::
+the following paper:
+.. code-block:: latex
  @inproceedings{Uricar-Franc-Hlavac-VISAPP-2012,
-    author =      {U{\v{r}}i{\v{c}}{\'{a}}{\v{r}}, Michal and Franc, Vojt{\v{e}}ch and Hlav{\'{a}}{\v{c}}, V{\'{a}}clav},
+    author =      {U\v{r}i\v{c}\'a\v{r}, Michal and Franc, Vojt\v{e}ch and Hlav\'a\v{c}, V\'{a}clav},
    title =       {Detector of Facial Landmarks Learned by the Structured Output {SVM}},
    year =        {2012},
    pages =       {547-556},
@@ -40,10 +44,12 @@ the following paper::
  }
 You should also cite `Bob`_, as a core framework, in which these bindings are
-based on::
+based on:
+.. code-block:: latex
  @inproceedings{Anjos_ACMMM_2012,
-    author = {A. Anjos AND L. El Shafey AND R. Wallace AND M. G\"unther AND C. McCool AND S. Marcel},
+    author = {Anjos, Andr\'e AND El Shafey, Laurent AND Wallace, Roy AND G\"unther, Manuel AND McCool, Christopher AND Marcel, S\'ebastien},
    title = {Bob: a free signal processing and machine learning toolbox for researchers},
    year = {2012},
    month = oct,

--- a/setup.py
+++ b/setup.py
@@ -73,12 +73,13 @@ setup(
    },
    classifiers = [
+      'Framework :: Bob',
      'Development Status :: 4 - Beta',
      'Intended Audience :: Developers',
      'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
      'Natural Language :: English',
      'Programming Language :: Python',
      'Topic :: Scientific/Engineering :: Artificial Intelligence',
-      ],
+    ],
-    )
+)