Modifications for sphinx documentation

latex support (still pseudo code issue)
doctest support for linux
Cmake launches make html && make doctest to test the doc



git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/ST_cythonize@1427 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: 58de6ec78d4368b99c9a81c9c229c4e7b075835a

13 files changed, 256 insertions, 32 deletions

diff --git a/biblio/bibliography.bib b/biblio/bibliography.bib
index 9fc01a5d..bd34f087 100644
--- a/biblio/bibliography.bib
+++ b/biblio/bibliography.bib
@@ -176,7 +176,7 @@ language={English},
 @article{RS62,
 	author={J. B. Rosser and L. Schoenfeld},
 	title={Approximate Formulas for some Functions of Prime Numbers},
-	journal= ijm,
+	journal= {ijm},
 	volume= 6,
 	year= 1962,
 	pages={64-94},
diff --git a/src/cython/CMakeLists.txt b/src/cython/CMakeLists.txt
index 19289977..9feca6ed 100644
--- a/src/cython/CMakeLists.txt
+++ b/src/cython/CMakeLists.txt
@@ -95,10 +95,16 @@ if(PYTHON_PATH AND CYTHON_PATH)
     # User version
     file(GLOB GUDHI_USER_DOC_IMAGES "${CMAKE_SOURCE_DIR}/doc/*/*.png")
     file(COPY ${GUDHI_USER_DOC_IMAGES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/doc/source/img")
+    # Biblio
+    file(GLOB GUDHI_BIB_FILES "${CMAKE_SOURCE_DIR}/biblio/*.bib")
+    file(COPY ${GUDHI_BIB_FILES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/doc/source/")
+    # Examples
+    file(GLOB GUDHI_EXAMPLES_FILES "${CMAKE_SOURCE_DIR}/src/cython/example/*.py")
+    file(COPY ${GUDHI_EXAMPLES_FILES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/doc/source/")
     if (UNIX)
       add_custom_target(html 
           WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc
-          COMMAND make html)
+          COMMAND make html && make doctest)
     else (UNIX)
       add_custom_target(html 
           WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc
diff --git a/src/cython/doc/source/alpha_complex_user.rst b/src/cython/doc/source/alpha_complex_user.rst
index ba920fe3..82b99be9 100644
--- a/src/cython/doc/source/alpha_complex_user.rst
+++ b/src/cython/doc/source/alpha_complex_user.rst
@@ -6,10 +6,192 @@ Definition
 
 .. include:: alpha_complex_sum.rst
 
-Alpha_complex is constructing a Simplex_tree using Delaunay Triangulation from
-CGAL (the Computational Geometry Algorithms Library).
-
-The complex is a template class requiring an Epick_d dD Geometry Kernel [16] from CGAL as template parameter.
+Alpha_complex is constructing a :doc:`Simplex_tree <simplex_tree_sum>` using
+`Delaunay Triangulation  <http://doc.cgal.org/latest/Triangulation/index.html#Chapter_Triangulations>`_ 
+:cite:`cgal:hdj-t-15b` from `CGAL <http://www.cgal.org/>`_ (the Computational Geometry Algorithms Library
+:cite:`cgal:eb-15b`).
 
 Remarks
-    When Alpha_complex is constructed with an infinite value of alpha, the complex is a Delaunay complex.
\ No newline at end of file
+^^^^^^^
+When Alpha_complex is constructed with an infinite value of :math:`\alpha`, the complex is a Delaunay complex.
+
+Example from points
+-------------------
+
+This example builds the Delaunay triangulation from the given points, and initializes the alpha complex with it:
+
+.. testcode::
+
+   import gudhi
+   alpha_complex = gudhi.AlphaComplex(points=[[1, 1], [7, 0], [4, 6], [9, 6], [0, 14], [2, 19], [9, 17]],
+                                      max_alpha_square=60.0)
+   result_str = 'Alpha complex is of dimension ' + repr(alpha_complex.dimension()) + ' - ' + \
+       repr(alpha_complex.num_simplices()) + ' simplices - ' + \
+       repr(alpha_complex.num_vertices()) + ' vertices.'
+   print(result_str)
+   for fitered_value in alpha_complex.get_filtered_tree():
+       print(fitered_value)
+
+The output is:
+
+.. testoutput::
+
+   Alpha complex is of dimension 2 - 25 simplices - 7 vertices.
+   ([0], 0.0)
+   ([1], 0.0)
+   ([2], 0.0)
+   ([3], 0.0)
+   ([4], 0.0)
+   ([5], 0.0)
+   ([6], 0.0)
+   ([2, 3], 6.25)
+   ([4, 5], 7.25)
+   ([0, 2], 8.5)
+   ([0, 1], 9.25)
+   ([1, 3], 10.0)
+   ([1, 2], 11.25)
+   ([1, 2, 3], 12.5)
+   ([0, 1, 2], 12.995867768595042)
+   ([5, 6], 13.25)
+   ([2, 4], 20.0)
+   ([4, 6], 22.736686390532547)
+   ([4, 5, 6], 22.736686390532547)
+   ([3, 6], 30.25)
+   ([2, 6], 36.5)
+   ([2, 3, 6], 36.5)
+   ([2, 4, 6], 37.24489795918368)
+   ([0, 4], 59.710743801652896)
+   ([0, 2, 4], 59.710743801652896)
+
+
+Algorithm
+---------
+
+Data structure
+^^^^^^^^^^^^^^
+
+In order to build the alpha complex, first, a Simplex tree is built from the cells of a Delaunay Triangulation.
+(The filtration value is set to NaN, which stands for unknown value):
+
+.. image::
+    img/alpha_complex_doc.png
+    :align: center
+    :alt: Simplex tree structure construction example
+
+Filtration value computation algorithm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. math::
+    \begin{algorithm}
+    \caption{Filtration value computation algorithm}\label{alpha}
+    \begin{algorithmic}
+    \For{i : dimension $\rightarrow$ 0}
+    \ForAll{$\sigma$ of dimension i}
+    \If {filtration($\sigma$) is NaN}
+    \State filtration($\sigma$) = $\alpha^2(\sigma)$
+    \EndIf
+    \ForAll{$\tau$ face of $\sigma$} \Comment{propagate alpha filtration value}
+    \If {filtration($\tau$) is not NaN} 
+    \State filtration($\tau$) = min (filtration($\tau$), filtration($\sigma$))
+    \Else
+    \If {$\tau$ is not Gabriel for $\sigma$} 
+    \State filtration($\tau$) = filtration($\sigma$)
+    \EndIf
+    \EndIf
+    \EndFor
+    \EndFor
+    \EndFor
+    \State make\_filtration\_non\_decreasing()
+    \State prune\_above\_filtration()
+    \end{algorithmic}
+    \end{algorithm}
+
+Dimension 2
+^^^^^^^^^^^
+
+From the example above, it means the algorithm looks into each triangle ([0,1,2], [0,2,4], [1,2,3], ...),
+computes the filtration value of the triangle, and then propagates the filtration value as described
+here:
+
+.. image::
+    img/alpha_complex_doc_420.png
+    :align: center
+    :alt: Filtration value propagation example
+
+Dimension 1
+^^^^^^^^^^^
+
+Then, the algorithm looks into each edge ([0,1], [0,2], [1,2], ...),
+computes the filtration value of the edge (in this case, propagation will have no effect).
+
+Dimension 0
+^^^^^^^^^^^
+
+Finally, the algorithm looks into each vertex ([0], [1], [2], [3], [4], [5] and [6]) and
+sets the filtration value (0 in case of a vertex - propagation will have no effect).
+
+Non decreasing filtration values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As the squared radii computed by CGAL are an approximation, it might happen that these alpha squared values do not
+quite define a proper filtration (i.e. non-decreasing with respect to inclusion).
+We fix that up by calling `Simplex_tree::make_filtration_non_decreasing()` (cf.
+`C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_).
+
+Prune above given filtration value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The simplex tree is pruned from the given maximum alpha squared value (cf. `Simplex_tree::prune_above_filtration()`
+int he `C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_).
+In the following example, the value is given by the user as argument of the program.
+
+
+Example from OFF file
+^^^^^^^^^^^^^^^^^^^^^
+
+This example builds the Delaunay triangulation from the points given by an OFF file, and initializes the alpha complex
+with it.
+
+
+Then, it is asked to display information about the alpha complex:
+
+.. testcode::
+
+   import gudhi
+   alpha_complex = gudhi.AlphaComplex(points=[[1, 1], [7, 0], [4, 6], [9, 6], [0, 14], [2, 19], [9, 17]],
+                                      max_alpha_square=59.0)
+   result_str = 'Alpha complex is of dimension ' + repr(alpha_complex.dimension()) + ' - ' + \
+       repr(alpha_complex.num_simplices()) + ' simplices - ' + \
+       repr(alpha_complex.num_vertices()) + ' vertices.'
+   print(result_str)
+   for fitered_value in alpha_complex.get_filtered_tree():
+       print(fitered_value)
+
+the program output is:
+
+.. testoutput::
+
+   Alpha complex is of dimension 2 - 23 simplices - 7 vertices.
+   ([0], 0.0)
+   ([1], 0.0)
+   ([2], 0.0)
+   ([3], 0.0)
+   ([4], 0.0)
+   ([5], 0.0)
+   ([6], 0.0)
+   ([2, 3], 6.25)
+   ([4, 5], 7.25)
+   ([0, 2], 8.5)
+   ([0, 1], 9.25)
+   ([1, 3], 10.0)
+   ([1, 2], 11.25)
+   ([1, 2, 3], 12.5)
+   ([0, 1, 2], 12.995867768595042)
+   ([5, 6], 13.25)
+   ([2, 4], 20.0)
+   ([4, 6], 22.736686390532547)
+   ([4, 5, 6], 22.736686390532547)
+   ([3, 6], 30.25)
+   ([2, 6], 36.5)
+   ([2, 3, 6], 36.5)
+   ([2, 4, 6], 37.24489795918368)
diff --git a/src/cython/doc/source/biblio.rst b/src/cython/doc/source/biblio.rst
new file mode 100644
index 00000000..66709265
--- /dev/null
+++ b/src/cython/doc/source/biblio.rst
@@ -0,0 +1,10 @@
+
+
+
+.. bibliography:: bibliography.bib
+   :filter: docnames
+   :style: alpha
+
+.. bibliography:: how_to_cite_cgal.bib
+   :filter: docnames
+   :style: unsrt
diff --git a/src/cython/doc/source/conf.py b/src/cython/doc/source/conf.py
index 094020f7..25e77e6d 100755
--- a/src/cython/doc/source/conf.py
+++ b/src/cython/doc/source/conf.py
@@ -39,6 +39,7 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.bibtex',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/src/cython/doc/source/cubical_complex_user.rst b/src/cython/doc/source/cubical_complex_user.rst
index 6ae67940..2efff680 100644
--- a/src/cython/doc/source/cubical_complex_user.rst
+++ b/src/cython/doc/source/cubical_complex_user.rst
@@ -1,6 +1,6 @@
-=========================
+===========================
 Cubical complex user manual
-=========================
+===========================
 Definition
 ----------
 
diff --git a/src/cython/doc/source/index.rst b/src/cython/doc/source/index.rst
index 2b17464a..5245d69d 100644
--- a/src/cython/doc/source/index.rst
+++ b/src/cython/doc/source/index.rst
@@ -3,9 +3,6 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. toctree::
-   :maxdepth: 2
-
 GUDHI's documentation
 #####################
 
@@ -17,10 +14,11 @@ Introduction
 
 The Gudhi library (Geometry Understanding in Higher Dimensions) is a generic
 open source C++ library for Computational Topology and Topological Data
-Analysis (TDA). The GUDHI library intends to help the development of new
-algorithmic solutions in TDA and their transfer to applications. It provides
-robust, efficient, flexible and easy to use implementations of
-state-of-the-art algorithms and data structures.
+Analysis (`TDA <https://en.wikipedia.org/wiki/Topological_data_analysis>`_).
+The GUDHI library intends to help the development of new algorithmic solutions
+in TDA and their transfer to applications. It provides robust, efficient,
+flexible and easy to use implementations of state-of-the-art algorithms and
+data structures.
 
 The current release of the GUDHI library includes:
 
@@ -29,8 +27,8 @@ The current release of the GUDHI library includes:
 * Simplication of simplicial complexes by edge contraction.
 
 All data-structures are generic and several of their aspects can be
-parameterized via template classes. We refer to [14] for a detailed
-description of the design of the library.
+parameterized via template classes. We refer to :cite:`gudhilibrary_ICMS14`
+for a detailed description of the design of the library.
 
 Data structures
 ***************
@@ -62,10 +60,4 @@ Toolbox
 Persistence cohomology
 ======================
 
-=====================================  =====================================  =====================================
-:Author: Clément Maria                 :Introduced in: GUDHI PYTHON 1.4.0     :Copyright: GPL v3
-=====================================  =====================================  =====================================
-
-
-
-
+.. include:: persistent_cohomology_sum.rst
diff --git a/src/cython/doc/source/persistent_cohomology_sum.rst b/src/cython/doc/source/persistent_cohomology_sum.rst
new file mode 100644
index 00000000..081399a5
--- /dev/null
+++ b/src/cython/doc/source/persistent_cohomology_sum.rst
@@ -0,0 +1,28 @@
+=====================================  =====================================  =====================================
+:Author: Clément Maria                 :Introduced in: GUDHI PYTHON 1.4.0     :Copyright: GPL v3
+=====================================  =====================================  =====================================
+
++---------------------------------------------+----------------------------------------------------------------------+
+| .. image::                                  | The theory of homology consists in attaching to a topological space  |
+|      img/3DTorus_poch.png                   | a sequence of (homology) groups, capturing global topological        |
+|                                             | features like connected components, holes, cavities, etc. Persistent |
+|                                             | homology studies the evolution -- birth, life and death -- of these  |
+|                                             | features when the topological space is changing. Consequently, the   |
+|                                             | theory is essentially composed of three elements: topological spaces,|
+|                                             | their homology groups and an evolution scheme.                       |
+|                                             |                                                                      |
+|                                             | Computation of persistent cohomology using the algorithm of          |
+|                                             | :cite:`DBLP:journals/dcg/SilvaMV11` and                              |
+|                                             | :cite:`DBLP:journals/corr/abs-1208-5018` and the Compressed          |
+|                                             | Annotation Matrix implementation of                                  |
+|                                             | :cite:`DBLP:conf/esa/BoissonnatDM13`.                                |
+|                                             |                                                                      |
++---------------------------------------------+----------------------------------------------------------------------+
+|  :doc:`persistent_cohomology_user`          | Please refer to each data structure that contains persistence        |
+|                                             | feature for reference:                                               |
+|                                             |                                                                      |
+|                                             | * :doc:`alpha_complex_ref`                                           |
+|                                             | * :doc:`cubical_complex_ref`                                         |
+|                                             | * :doc:`simplex_tree_ref`                                            |
+|                                             | * :doc:`witness_complex_ref`                                         |
++---------------------------------------------+----------------------------------------------------------------------+
diff --git a/src/cython/doc/source/persistent_cohomology_user.rst b/src/cython/doc/source/persistent_cohomology_user.rst
new file mode 100644
index 00000000..41b6a3e3
--- /dev/null
+++ b/src/cython/doc/source/persistent_cohomology_user.rst
@@ -0,0 +1,7 @@
+=================================
+Persistent cohomology user manual
+=================================
+Definition
+----------
+
+.. include:: persistent_cohomology_sum.rst
diff --git a/src/cython/doc/source/simplex_tree_sum.rst b/src/cython/doc/source/simplex_tree_sum.rst
index cc02ccc2..ffdb2cf4 100644
--- a/src/cython/doc/source/simplex_tree_sum.rst
+++ b/src/cython/doc/source/simplex_tree_sum.rst
@@ -7,8 +7,7 @@
 |      img/Simplex_tree_representation.png  | representing general (filtered) simplicial complexes.                |
 |                                           |                                                                      |
 |                                           | The data structure is described in                                   |
-|                                           | `this document <http://dx.doi.org/10.1007/s00453-014-9887-3>`_       |
+|                                           | :cite:`boissonnatmariasimplextreealgorithmica`                       |
 +-------------------------------------------+----------------------------------------------------------------------+
 | :doc:`simplex_tree_user`                  | :doc:`simplex_tree_ref`                                              |
 +-------------------------------------------+----------------------------------------------------------------------+
- 
\ No newline at end of file
diff --git a/src/cython/doc/source/simplex_tree_user.rst b/src/cython/doc/source/simplex_tree_user.rst
index e1f6e93d..b07bd449 100644
--- a/src/cython/doc/source/simplex_tree_user.rst
+++ b/src/cython/doc/source/simplex_tree_user.rst
@@ -5,4 +5,3 @@ Definition
 ----------
 
 .. include:: simplex_tree_sum.rst
-
diff --git a/src/cython/doc/source/witness_complex_ref.rst b/src/cython/doc/source/witness_complex_ref.rst
index 79e39739..c78760cb 100644
--- a/src/cython/doc/source/witness_complex_ref.rst
+++ b/src/cython/doc/source/witness_complex_ref.rst
@@ -1,6 +1,6 @@
-===============================
+================================
 Witness complex reference manual
-===============================
+================================
 
 .. autoclass:: gudhi.WitnessComplex
    :members:
diff --git a/src/cython/doc/source/witness_complex_user.rst b/src/cython/doc/source/witness_complex_user.rst
index 3b4c3891..698e5441 100644
--- a/src/cython/doc/source/witness_complex_user.rst
+++ b/src/cython/doc/source/witness_complex_user.rst
@@ -1,6 +1,6 @@
-==========================
+===========================
 Witness complex user manual
-==========================
+===========================
 Definition
 ----------