Cython documentation. Sphinx style.

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

Former-commit-id: ed09c0f54fda05d4147f5680db6f626e9a5d1a92

5 files changed, 622 insertions, 29 deletions

diff --git a/src/cython/src/cython/alpha_complex.pyx b/src/cython/src/cython/alpha_complex.pyx
index 0d44cbce..6f8f5eca 100644
--- a/src/cython/src/cython/alpha_complex.pyx
+++ b/src/cython/src/cython/alpha_complex.pyx
@@ -59,11 +59,35 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi":
 
 # AlphaComplex python interface
 cdef class AlphaComplex:
+    """AlphaComplex is a simplicial complex constructed from the finite cells
+    of a Delaunay Triangulation.
+
+    The filtration value of each simplex is computed as the square of the
+    circumradius of the simplex if the circumsphere is empty (the simplex is
+    then said to be Gabriel), and as the minimum of the filtration values of
+    the codimension 1 cofaces that make it not Gabriel otherwise.
+
+    All simplices that have a filtration value strictly greater than a given
+    alpha squared value are not inserted into the complex.
+
+    .. note::
+
+        When Alpha_complex is constructed with an infinite value of alpha, the
+        complex is a Delaunay complex.
+
+    """
+
     cdef Alpha_complex_interface * thisptr
 
     cdef Alpha_complex_persistence_interface * pcohptr
 
     def __cinit__(self, points=None, max_alpha_square=float('inf')):
+        """AlphaComplex constructor.
+
+        Args:
+           points (list): A list of points in d-Dimension.
+           max_alpha_square (float): Maximum Alpha square value.
+        """
         if points is not None:
             self.thisptr = new Alpha_complex_interface(points,
                                                        max_alpha_square)
@@ -75,36 +99,97 @@ cdef class AlphaComplex:
             del self.pcohptr
 
     def get_filtration(self):
+        """This function returns the main simplicial complex filtration value.
+
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.filtration()
 
     def filtration(self, simplex):
+        """This function returns the simplicial complex filtration value for a
+        given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.simplex_filtration(simplex)
 
     def set_filtration(self, filtration):
+        """This function sets the main simplicial complex filtration value.
+
+        :param filtration: The filtration value.
+        :type filtration: float.
+        """
         self.thisptr.set_filtration(<double> filtration)
 
     def initialize_filtration(self):
+        """This function initializes and sorts the simplicial complex
+        filtration vector.
+
+        .. note::
+
+            This function must be launched before persistence, betti_numbers,
+            persistent_betti_numbers or get_filtered_tree after inserting or
+            removing simplices.
+        """
         self.thisptr.initialize_filtration()
 
     def num_vertices(self):
+        """This function returns the number of vertices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of vertices.
+        """
         return self.thisptr.num_vertices()
 
     def num_simplices(self):
+        """This function returns the number of simplices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of simplices.
+        """
         return self.thisptr.num_simplices()
 
     def dimension(self):
+        """This function returns the dimension of the simplicial complex.
+
+        :returns:  int -- the simplicial complex dimension.
+        """
         return self.thisptr.dimension()
 
-    def set_dimension(self, dim):
-        self.thisptr.set_dimension(<int>dim)
+    def set_dimension(self, dimension):
+        """This function sets the dimension of the simplicial complex.
+
+        :param dimension: The new dimension value.
+        :type dimension: int.
+        """
+        self.thisptr.set_dimension(<int>dimension)
 
     def find(self, simplex):
+        """This function returns if the N-simplex was found in the simplicial
+        complex or not.
+
+        :param simplex: The N-simplex to find, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         return self.thisptr.find_simplex(complex)
 
     def insert(self, simplex, filtration=0.0):
+        """This function inserts the given N-simplex with the given filtration
+        value (default value is '0.0').
+
+        :param simplex: The N-simplex to insert, represented by a list of
+        vertex.
+        :type simplex: list of int.
+        :param filtration: The filtration value of the simplex.
+        :type filtration: float.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -112,6 +197,12 @@ cdef class AlphaComplex:
                                                         <double>filtration)
 
     def get_filtered_tree(self):
+        """This function returns the tree sorted by increasing filtration
+        values.
+
+        :returns:  list of tuples(simplex, filtration) -- the tree sorted by
+        increasing filtration values.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
             = self.thisptr.get_filtered_tree()
         ct = []
@@ -122,9 +213,17 @@ cdef class AlphaComplex:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_skeleton_tree(self, dim):
+    def get_skeleton_tree(self, dimension):
+        """This function returns the tree skeleton of a maximum given
+        dimension.
+
+        :param dimension: The skeleton dimension value.
+        :type dimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the skeleton tree
+        of a maximum dimension.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_skeleton_tree(<int>dim)
+            = self.thisptr.get_skeleton_tree(<int>dimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -134,6 +233,13 @@ cdef class AlphaComplex:
         return ct
 
     def get_star_tree(self, simplex):
+        """This function returns the star tree of a given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  list of tuples(simplex, filtration) -- the star tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -147,12 +253,23 @@ cdef class AlphaComplex:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_coface_tree(self, simplex, dim):
+    def get_coface_tree(self, simplex, codimension):
+        """This function returns the coface tree of a given N-simplex with a
+        given codimension.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :param codimension: The codimension. If codimension = 0, all cofaces
+        are returned (equivalent of get_star_tree function)
+        :type codimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the coface tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_coface_tree(complex, <int>dim)
+            = self.thisptr.get_coface_tree(complex, <int>codimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -162,22 +279,52 @@ cdef class AlphaComplex:
         return ct
 
     def remove_maximal_simplex(self, simplex):
+        """This function removes a given maximal N-simplex from the simplicial
+        complex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        """
         self.thisptr.remove_maximal_simplex(simplex)
 
     def get_point(self, vertex):
+        """This function returns the point corresponding to a given vertex.
+
+        :param vertex: The vertex.
+        :type vertex: int.
+        :returns:  list of float -- the point.
+        """
         cdef vector[double] point = self.thisptr.get_point(vertex)
         return point
 
-    def persistence(self, homology_coeff_field=11, min_persistence=0):
+    def persistence(self, homology_coeff_field=11, min_persistence=0.0):
+        """This function returns the persistence of the simplicial complex.
+
+        :param homology_coeff_field: The homology coefficient field. Must be a
+        prime number
+        :type homology_coeff_field: int.
+        :param min_persistence: The minimum persistence value to take into
+        account (strictly greater than min_persistence). Default value is 0.0.
+        Sets min_persistence to -1.0 to see all values.
+        :type min_persistence: float.
+        :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a
+        simplex.
+        """
         if self.pcohptr != NULL:
             del self.pcohptr
         self.pcohptr = new Alpha_complex_persistence_interface(self.thisptr)
         cdef vector[pair[int, pair[double, double]]] persistence_result
         if self.pcohptr != NULL:
-            persistence_result = self.pcohptr.get_persistence(homology_coeff_field, min_persistence)
+            persistence_result \
+                = self.pcohptr.get_persistence(homology_coeff_field,
+                                               min_persistence)
         return persistence_result
 
     def betti_numbers(self):
+        """This function returns the Betti numbers of the simplicial complex.
+
+        :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]).
+        """
         cdef vector[int] bn_result
         if self.pcohptr != NULL:
             bn_result = self.pcohptr.betti_numbers()
@@ -187,10 +334,25 @@ cdef class AlphaComplex:
         return bn_result
 
     def persistent_betti_numbers(self, from_value, to_value):
+        """This function returns the persistent Betti numbers of the
+        simplicial complex.
+
+        :param from_value: The persistence birth limit to be added in the
+        numbers (persistent birth <= from_value).
+        :type from_value: float.
+        :param to_value: The persistence death limit to be added in the
+        numbers (persistent death > to_value).
+        :type to_value: float.
+
+        :returns: list of int -- The persistent Betti numbers ([B0, B1, ...,
+        Bn]).
+        """
         cdef vector[int] pbn_result
         if self.pcohptr != NULL:
-            pbn_result = self.pcohptr.persistent_betti_numbers(<double>from_value, <double>to_value)
+            pbn_result \
+                = self.pcohptr.persistent_betti_numbers(<double>from_value,
+                                                        <double>to_value)
         else:
-            print("persistent_betti_numbers function requires persistence function"
-                  " to be launched first.")
+            print("persistent_betti_numbers function requires persistence "
+                  "function to be launched first.")
         return pbn_result
diff --git a/src/cython/src/cython/mini_simplex_tree.pyx b/src/cython/src/cython/mini_simplex_tree.pyx
index 3d216fe2..c6725226 100644
--- a/src/cython/src/cython/mini_simplex_tree.pyx
+++ b/src/cython/src/cython/mini_simplex_tree.pyx
@@ -61,6 +61,15 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi":
 
 # MiniSimplexTree python interface
 cdef class MiniSimplexTree:
+    """The simplex tree is an efficient and flexible data structure for
+    representing general (filtered) simplicial complexes. The data structure
+    is described in Jean-Daniel Boissonnat and Clément Maria. The Simplex
+    Tree: An Efficient Data Structure for General Simplicial Complexes.
+    Algorithmica, pages 1–22, 2014.
+
+    This class is a non-filtered, with keys, and non contiguous vertices
+    version of the simplex tree.
+    """
     cdef Simplex_tree_interface_mini * thisptr
 
     cdef Mini_simplex_tree_persistence_interface * pcohptr
@@ -75,36 +84,97 @@ cdef class MiniSimplexTree:
             del self.pcohptr
 
     def get_filtration(self):
+        """This function returns the main simplicial complex filtration value.
+
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.filtration()
 
     def filtration(self, simplex):
+        """This function returns the simplicial complex filtration value for a
+        given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.simplex_filtration(simplex)
 
     def set_filtration(self, filtration):
+        """This function sets the main simplicial complex filtration value.
+
+        :param filtration: The filtration value.
+        :type filtration: float.
+        """
         self.thisptr.set_filtration(<double> filtration)
 
     def initialize_filtration(self):
+        """This function initializes and sorts the simplicial complex
+        filtration vector.
+
+        .. note::
+
+            This function must be launched before persistence, betti_numbers,
+            persistent_betti_numbers or get_filtered_tree after inserting or
+            removing simplices.
+        """
         self.thisptr.initialize_filtration()
 
     def num_vertices(self):
+        """This function returns the number of vertices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of vertices.
+        """
         return self.thisptr.num_vertices()
 
     def num_simplices(self):
+        """This function returns the number of simplices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of simplices.
+        """
         return self.thisptr.num_simplices()
 
     def dimension(self):
+        """This function returns the dimension of the simplicial complex.
+
+        :returns:  int -- the simplicial complex dimension.
+        """
         return self.thisptr.dimension()
 
-    def set_dimension(self, dim):
-        self.thisptr.set_dimension(<int>dim)
+    def set_dimension(self, dimension):
+        """This function sets the dimension of the simplicial complex.
+
+        :param dimension: The new dimension value.
+        :type dimension: int.
+        """
+        self.thisptr.set_dimension(<int>dimension)
 
     def find(self, simplex):
+        """This function returns if the N-simplex was found in the simplicial
+        complex or not.
+
+        :param simplex: The N-simplex to find, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         return self.thisptr.find_simplex(complex)
 
     def insert(self, simplex, filtration=0.0):
+        """This function inserts the given N-simplex with the given filtration
+        value (default value is '0.0').
+
+        :param simplex: The N-simplex to insert, represented by a list of
+        vertex.
+        :type simplex: list of int.
+        :param filtration: The filtration value of the simplex.
+        :type filtration: float.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -112,6 +182,12 @@ cdef class MiniSimplexTree:
                                                         <double>filtration)
 
     def get_filtered_tree(self):
+        """This function returns the tree sorted by increasing filtration
+        values.
+
+        :returns:  list of tuples(simplex, filtration) -- the tree sorted by
+        increasing filtration values.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
             = self.thisptr.get_filtered_tree()
         ct = []
@@ -122,9 +198,17 @@ cdef class MiniSimplexTree:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_skeleton_tree(self, dim):
+    def get_skeleton_tree(self, dimension):
+        """This function returns the tree skeleton of a maximum given
+        dimension.
+
+        :param dimension: The skeleton dimension value.
+        :type dimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the skeleton tree
+        of a maximum dimension.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_skeleton_tree(<int>dim)
+            = self.thisptr.get_skeleton_tree(<int>dimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -134,6 +218,13 @@ cdef class MiniSimplexTree:
         return ct
 
     def get_star_tree(self, simplex):
+        """This function returns the star tree of a given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  list of tuples(simplex, filtration) -- the star tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -147,12 +238,23 @@ cdef class MiniSimplexTree:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_coface_tree(self, simplex, dim):
+    def get_coface_tree(self, simplex, codimension):
+        """This function returns the coface tree of a given N-simplex with a
+        given codimension.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :param codimension: The codimension. If codimension = 0, all cofaces
+        are returned (equivalent of get_star_tree function)
+        :type codimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the coface tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_coface_tree(complex, <int>dim)
+            = self.thisptr.get_coface_tree(complex, <int>codimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -162,9 +264,27 @@ cdef class MiniSimplexTree:
         return ct
 
     def remove_maximal_simplex(self, simplex):
+        """This function removes a given maximal N-simplex from the simplicial
+        complex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        """
         self.thisptr.remove_maximal_simplex(simplex)
 
     def persistence(self, homology_coeff_field=11):
+        """This function returns the persistence of the simplicial complex.
+
+        :param homology_coeff_field: The homology coefficient field. Must be a
+        prime number
+        :type homology_coeff_field: int.
+        :param min_persistence: The minimum persistence value to take into
+        account (strictly greater than min_persistence). Default value is 0.0.
+        Sets min_persistence to -1.0 to see all values.
+        :type min_persistence: float.
+        :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a
+        simplex.
+        """
         if self.pcohptr != NULL:
             del self.pcohptr
         self.pcohptr = new Mini_simplex_tree_persistence_interface(self.thisptr)
@@ -174,6 +294,10 @@ cdef class MiniSimplexTree:
         return persistence_result
 
     def betti_numbers(self):
+        """This function returns the Betti numbers of the simplicial complex.
+
+        :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]).
+        """
         cdef vector[int] bn_result
         if self.pcohptr != NULL:
             bn_result = self.pcohptr.betti_numbers()
@@ -183,6 +307,19 @@ cdef class MiniSimplexTree:
         return bn_result
 
     def persistent_betti_numbers(self, from_value, to_value):
+        """This function returns the persistent Betti numbers of the
+        simplicial complex.
+
+        :param from_value: The persistence birth limit to be added in the
+        numbers (persistent birth <= from_value).
+        :type from_value: float.
+        :param to_value: The persistence death limit to be added in the
+        numbers (persistent death > to_value).
+        :type to_value: float.
+
+        :returns: list of int -- The persistent Betti numbers ([B0, B1, ...,
+        Bn]).
+        """
         cdef vector[int] pbn_result
         if self.pcohptr != NULL:
             pbn_result = self.pcohptr.persistent_betti_numbers(<double>from_value, <double>to_value)
diff --git a/src/cython/src/cython/persistence_graphical_tools.py b/src/cython/src/cython/persistence_graphical_tools.py
index b845e405..6cacf4a5 100755
--- a/src/cython/src/cython/persistence_graphical_tools.py
+++ b/src/cython/src/cython/persistence_graphical_tools.py
@@ -35,12 +35,17 @@ palette = ['#ff0000', '#00ff00', '#0000ff', '#00ffff', '#ff00ff', '#ffff00',
            '#008888']
 
 def show_palette_values():
+    """This function shows palette color values in function of the dimension.
+
+    :returns: plot -- An horizontal bar plot of dimensions color.
+    """
     colors = []
     for color in palette:
         colors.append(color)
 
     y_pos = np.arange(len(palette))
 
+    # alpha=0.4 is realy usefull for ugly colors
     plt.barh(y_pos, y_pos + 1, align='center', alpha=0.4, color=colors)
     plt.ylabel('Dimension')
     plt.title('Dimension palette values')
@@ -48,6 +53,12 @@ def show_palette_values():
     plt.show()
 
 def bar_code_persistence(persistence):
+    """This function plots the persistence bar code.
+
+    :param persistence: The persistence to plot.
+    :type persistence: list of tuples(dimension, tuple(birth, death)).
+    :returns: plot -- An horizontal bar plot of persistence.
+    """
     # Look for minimum birth date and maximum death date for plot optimisation
     max_death = 0
     min_birth = persistence[0][1][0]
diff --git a/src/cython/src/cython/rips_complex.pyx b/src/cython/src/cython/rips_complex.pyx
index 52a3cfd8..13e82230 100644
--- a/src/cython/src/cython/rips_complex.pyx
+++ b/src/cython/src/cython/rips_complex.pyx
@@ -63,12 +63,30 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi":
 
 # RipsComplex python interface
 cdef class RipsComplex:
+    """RipsComplex is a simplicial complex constructed from a list of points.
+
+    Each point Pn is inserted as a vertex in the simplicial complex with a
+    null filtration value.
+
+    A N-simplex represented by the list of vertices Vi, ..., Vj is inserted in
+    the simplicial complex if all the points Pi, ..., Pj corresponding to the
+    vertices are within a distance less or equal to a given maximum edge length
+    value, and if N (dimension of the N-simplex) is less or equal to a given
+    maximum dimension.
+    """
     cdef Rips_complex_interface * thisptr
 
     cdef Rips_complex_persistence_interface * pcohptr
 
     def __cinit__(self, points=None, max_dimension=3,
                   max_edge_length=float('inf')):
+        """RipsComplex constructor.
+
+        Args:
+           points (list): A list of points in d-Dimension.
+           max_dimension (int): Maximum dimension of the N-simplex to insert.
+           max_edge_length (float): Maximum edge length, or distance.
+        """
         self.thisptr = new Rips_complex_interface()
         # Constructor from graph expansion
         if points is not None:
@@ -82,36 +100,97 @@ cdef class RipsComplex:
             del self.pcohptr
 
     def get_filtration(self):
+        """This function returns the main simplicial complex filtration value.
+
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.filtration()
 
     def filtration(self, simplex):
+        """This function returns the simplicial complex filtration value for a
+        given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.simplex_filtration(simplex)
 
     def set_filtration(self, filtration):
+        """This function sets the main simplicial complex filtration value.
+
+        :param filtration: The filtration value.
+        :type filtration: float.
+        """
         self.thisptr.set_filtration(<double> filtration)
 
     def initialize_filtration(self):
+        """This function initializes and sorts the simplicial complex
+        filtration vector.
+
+        .. note::
+
+            This function must be launched before persistence, betti_numbers,
+            persistent_betti_numbers or get_filtered_tree after inserting or
+            removing simplices.
+        """
         self.thisptr.initialize_filtration()
 
     def num_vertices(self):
+        """This function returns the number of vertices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of vertices.
+        """
         return self.thisptr.num_vertices()
 
     def num_simplices(self):
+        """This function returns the number of simplices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of simplices.
+        """
         return self.thisptr.num_simplices()
 
     def dimension(self):
+        """This function returns the dimension of the simplicial complex.
+
+        :returns:  int -- the simplicial complex dimension.
+        """
         return self.thisptr.dimension()
 
-    def set_dimension(self, dim):
-        self.thisptr.set_dimension(<int>dim)
+    def set_dimension(self, dimension):
+        """This function sets the dimension of the simplicial complex.
+
+        :param dimension: The new dimension value.
+        :type dimension: int.
+        """
+        self.thisptr.set_dimension(<int>dimension)
 
     def find(self, simplex):
+        """This function returns if the N-simplex was found in the simplicial
+        complex or not.
+
+        :param simplex: The N-simplex to find, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         return self.thisptr.find_simplex(complex)
 
     def insert(self, simplex, filtration=0.0):
+        """This function inserts the given N-simplex with the given filtration
+        value (default value is '0.0').
+
+        :param simplex: The N-simplex to insert, represented by a list of
+        vertex.
+        :type simplex: list of int.
+        :param filtration: The filtration value of the simplex.
+        :type filtration: float.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -119,6 +198,12 @@ cdef class RipsComplex:
                                                         <double>filtration)
 
     def get_filtered_tree(self):
+        """This function returns the tree sorted by increasing filtration
+        values.
+
+        :returns:  list of tuples(simplex, filtration) -- the tree sorted by
+        increasing filtration values.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
             = self.thisptr.get_filtered_tree()
         ct = []
@@ -129,9 +214,17 @@ cdef class RipsComplex:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_skeleton_tree(self, dim):
+    def get_skeleton_tree(self, dimension):
+        """This function returns the tree skeleton of a maximum given
+        dimension.
+
+        :param dimension: The skeleton dimension value.
+        :type dimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the skeleton tree
+        of a maximum dimension.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_skeleton_tree(<int>dim)
+            = self.thisptr.get_skeleton_tree(<int>dimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -141,6 +234,13 @@ cdef class RipsComplex:
         return ct
 
     def get_star_tree(self, simplex):
+        """This function returns the star tree of a given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  list of tuples(simplex, filtration) -- the star tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -154,12 +254,23 @@ cdef class RipsComplex:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_coface_tree(self, simplex, dim):
+    def get_coface_tree(self, simplex, codimension):
+        """This function returns the coface tree of a given N-simplex with a
+        given codimension.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :param codimension: The codimension. If codimension = 0, all cofaces
+        are returned (equivalent of get_star_tree function)
+        :type codimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the coface tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_coface_tree(complex, <int>dim)
+            = self.thisptr.get_coface_tree(complex, <int>codimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -169,9 +280,27 @@ cdef class RipsComplex:
         return ct
 
     def remove_maximal_simplex(self, simplex):
+        """This function removes a given maximal N-simplex from the simplicial
+        complex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        """
         self.thisptr.remove_maximal_simplex(simplex)
 
     def persistence(self, homology_coeff_field=11, min_persistence=0):
+        """This function returns the persistence of the simplicial complex.
+
+        :param homology_coeff_field: The homology coefficient field. Must be a
+        prime number
+        :type homology_coeff_field: int.
+        :param min_persistence: The minimum persistence value to take into
+        account (strictly greater than min_persistence). Default value is 0.0.
+        Sets min_persistence to -1.0 to see all values.
+        :type min_persistence: float.
+        :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a
+        simplex.
+        """
         if self.pcohptr != NULL:
             del self.pcohptr
         self.pcohptr = new Rips_complex_persistence_interface(self.thisptr)
@@ -181,6 +310,10 @@ cdef class RipsComplex:
         return persistence_result
 
     def betti_numbers(self):
+        """This function returns the Betti numbers of the simplicial complex.
+
+        :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]).
+        """
         cdef vector[int] bn_result
         if self.pcohptr != NULL:
             bn_result = self.pcohptr.betti_numbers()
@@ -190,6 +323,19 @@ cdef class RipsComplex:
         return bn_result
 
     def persistent_betti_numbers(self, from_value, to_value):
+        """This function returns the persistent Betti numbers of the
+        simplicial complex.
+
+        :param from_value: The persistence birth limit to be added in the
+        numbers (persistent birth <= from_value).
+        :type from_value: float.
+        :param to_value: The persistence death limit to be added in the
+        numbers (persistent death > to_value).
+        :type to_value: float.
+
+        :returns: list of int -- The persistent Betti numbers ([B0, B1, ...,
+        Bn]).
+        """
         cdef vector[int] pbn_result
         if self.pcohptr != NULL:
             pbn_result = self.pcohptr.persistent_betti_numbers(<double>from_value, <double>to_value)
diff --git a/src/cython/src/cython/simplex_tree.pyx b/src/cython/src/cython/simplex_tree.pyx
index b84b7758..c5cb7595 100644
--- a/src/cython/src/cython/simplex_tree.pyx
+++ b/src/cython/src/cython/simplex_tree.pyx
@@ -61,6 +61,15 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi":
 
 # SimplexTree python interface
 cdef class SimplexTree:
+    """The simplex tree is an efficient and flexible data structure for
+    representing general (filtered) simplicial complexes. The data structure
+    is described in Jean-Daniel Boissonnat and Clément Maria. The Simplex
+    Tree: An Efficient Data Structure for General Simplicial Complexes.
+    Algorithmica, pages 1–22, 2014.
+
+    This class is a filtered, with keys, and non contiguous vertices version
+    of the simplex tree.
+    """
     cdef Simplex_tree_interface_full_featured * thisptr
 
     cdef Simplex_tree_persistence_interface * pcohptr
@@ -75,36 +84,97 @@ cdef class SimplexTree:
             del self.pcohptr
 
     def get_filtration(self):
+        """This function returns the main simplicial complex filtration value.
+
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.filtration()
 
     def filtration(self, simplex):
+        """This function returns the simplicial complex filtration value for a
+        given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  float -- the simplicial complex filtration value.
+        """
         return self.thisptr.simplex_filtration(simplex)
 
     def set_filtration(self, filtration):
+        """This function sets the main simplicial complex filtration value.
+
+        :param filtration: The filtration value.
+        :type filtration: float.
+        """
         self.thisptr.set_filtration(<double> filtration)
 
     def initialize_filtration(self):
+        """This function initializes and sorts the simplicial complex
+        filtration vector.
+
+        .. note::
+
+            This function must be launched before persistence, betti_numbers,
+            persistent_betti_numbers or get_filtered_tree after inserting or
+            removing simplices.
+        """
         self.thisptr.initialize_filtration()
 
     def num_vertices(self):
+        """This function returns the number of vertices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of vertices.
+        """
         return self.thisptr.num_vertices()
 
     def num_simplices(self):
+        """This function returns the number of simplices of the simplicial
+        complex.
+
+        :returns:  int -- the simplicial complex number of simplices.
+        """
         return self.thisptr.num_simplices()
 
     def dimension(self):
+        """This function returns the dimension of the simplicial complex.
+
+        :returns:  int -- the simplicial complex dimension.
+        """
         return self.thisptr.dimension()
 
-    def set_dimension(self, dim):
-        self.thisptr.set_dimension(<int>dim)
+    def set_dimension(self, dimension):
+        """This function sets the dimension of the simplicial complex.
+
+        :param dimension: The new dimension value.
+        :type dimension: int.
+        """
+        self.thisptr.set_dimension(<int>dimension)
 
     def find(self, simplex):
+        """This function returns if the N-simplex was found in the simplicial
+        complex or not.
+
+        :param simplex: The N-simplex to find, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         return self.thisptr.find_simplex(complex)
 
     def insert(self, simplex, filtration=0.0):
+        """This function inserts the given N-simplex with the given filtration
+        value (default value is '0.0').
+
+        :param simplex: The N-simplex to insert, represented by a list of
+        vertex.
+        :type simplex: list of int.
+        :param filtration: The filtration value of the simplex.
+        :type filtration: float.
+        :returns:  bool -- true if the simplex was found, false otherwise.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -112,6 +182,12 @@ cdef class SimplexTree:
                                                         <double>filtration)
 
     def get_filtered_tree(self):
+        """This function returns the tree sorted by increasing filtration
+        values.
+
+        :returns:  list of tuples(simplex, filtration) -- the tree sorted by
+        increasing filtration values.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
             = self.thisptr.get_filtered_tree()
         ct = []
@@ -122,9 +198,17 @@ cdef class SimplexTree:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_skeleton_tree(self, dim):
+    def get_skeleton_tree(self, dimension):
+        """This function returns the tree skeleton of a maximum given
+        dimension.
+
+        :param dimension: The skeleton dimension value.
+        :type dimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the skeleton tree
+        of a maximum dimension.
+        """
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_skeleton_tree(<int>dim)
+            = self.thisptr.get_skeleton_tree(<int>dimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -134,6 +218,13 @@ cdef class SimplexTree:
         return ct
 
     def get_star_tree(self, simplex):
+        """This function returns the star tree of a given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :returns:  list of tuples(simplex, filtration) -- the star tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
@@ -147,12 +238,23 @@ cdef class SimplexTree:
             ct.append((v, filtered_complex.second))
         return ct
 
-    def get_coface_tree(self, simplex, dim):
+    def get_coface_tree(self, simplex, codimension):
+        """This function returns the coface tree of a given N-simplex with a
+        given codimension.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :param codimension: The codimension. If codimension = 0, all cofaces
+        are returned (equivalent of get_star_tree function)
+        :type codimension: int.
+        :returns:  list of tuples(simplex, filtration) -- the coface tree of a
+        simplex.
+        """
         cdef vector[int] complex
         for i in simplex:
             complex.push_back(i)
         cdef vector[pair[vector[int], double]] coface_tree \
-            = self.thisptr.get_coface_tree(complex, <int>dim)
+            = self.thisptr.get_coface_tree(complex, <int>codimension)
         ct = []
         for filtered_complex in coface_tree:
             v = []
@@ -162,9 +264,27 @@ cdef class SimplexTree:
         return ct
 
     def remove_maximal_simplex(self, simplex):
+        """This function removes a given maximal N-simplex from the simplicial
+        complex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        """
         self.thisptr.remove_maximal_simplex(simplex)
 
     def persistence(self, homology_coeff_field=11, min_persistence=0):
+        """This function returns the persistence of the simplicial complex.
+
+        :param homology_coeff_field: The homology coefficient field. Must be a
+        prime number
+        :type homology_coeff_field: int.
+        :param min_persistence: The minimum persistence value to take into
+        account (strictly greater than min_persistence). Default value is 0.0.
+        Sets min_persistence to -1.0 to see all values.
+        :type min_persistence: float.
+        :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a
+        simplex.
+        """
         if self.pcohptr != NULL:
             del self.pcohptr
         self.pcohptr = new Simplex_tree_persistence_interface(self.thisptr)
@@ -174,6 +294,10 @@ cdef class SimplexTree:
         return persistence_result
 
     def betti_numbers(self):
+        """This function returns the Betti numbers of the simplicial complex.
+
+        :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]).
+        """
         cdef vector[int] bn_result
         if self.pcohptr != NULL:
             bn_result = self.pcohptr.betti_numbers()
@@ -183,6 +307,19 @@ cdef class SimplexTree:
         return bn_result
 
     def persistent_betti_numbers(self, from_value, to_value):
+        """This function returns the persistent Betti numbers of the
+        simplicial complex.
+
+        :param from_value: The persistence birth limit to be added in the
+        numbers (persistent birth <= from_value).
+        :type from_value: float.
+        :param to_value: The persistence death limit to be added in the
+        numbers (persistent death > to_value).
+        :type to_value: float.
+
+        :returns: list of int -- The persistent Betti numbers ([B0, B1, ...,
+        Bn]).
+        """
         cdef vector[int] pbn_result
         if self.pcohptr != NULL:
             pbn_result = self.pcohptr.persistent_betti_numbers(<double>from_value, <double>to_value)