Merge pull request #189 from mglisse/doc

Link the doc for subsampling & point file readers, some reorg

7 files changed, 78 insertions, 41 deletions

diff --git a/src/python/doc/reader_utils_ref.rst b/src/python/doc/diagram_readers_ref.rst
index b8977a5a..c79daf9c 100644
--- a/src/python/doc/reader_utils_ref.rst
+++ b/src/python/doc/diagram_readers_ref.rst
@@ -2,13 +2,9 @@
 
 .. To get rid of WARNING: document isn't included in any toctree
 
-=============================
-Reader utils reference manual
-=============================
-
-.. autofunction:: gudhi.read_points_from_off_file
-
-.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file
+================================
+Diagram readers reference manual
+================================
 
 .. autofunction:: gudhi.read_persistence_intervals_grouped_by_dimension
 
diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst
index c36a578f..3387a64f 100644
--- a/src/python/doc/index.rst
+++ b/src/python/doc/index.rst
@@ -6,8 +6,8 @@ GUDHI Python modules documentation
      :alt: Gudhi banner
      :figclass: align-center
 
-Complexes
-*********
+Data structures for cell complexes
+**********************************
 
 Cubical complexes
 =================
@@ -17,18 +17,26 @@ Cubical complexes
 Simplicial complexes
 ====================
 
+Simplex tree
+------------
+
+.. include:: simplex_tree_sum.inc
+
+Filtrations and reconstructions
+*******************************
+
 Alpha complex
--------------
+=============
 
 .. include:: alpha_complex_sum.inc
 
 Rips complex
-------------
+============
 
 .. include:: rips_complex_sum.inc
 
 Witness complex
----------------
+===============
 
 .. include:: witness_complex_sum.inc
 
@@ -37,16 +45,10 @@ Cover complexes
 
 .. include:: nerve_gic_complex_sum.inc
 
-Data structures and basic operations
-************************************
-
-Data structures
-===============
-
-Simplex tree
-------------
+Tangential complex
+==================
 
-.. include:: simplex_tree_sum.inc
+.. include:: tangential_complex_sum.inc
 
 Topological descriptors computation
 ***********************************
@@ -56,15 +58,6 @@ Persistence cohomology
 
 .. include:: persistent_cohomology_sum.inc
 
-Manifold reconstruction
-***********************
-
-Tangential complex
-==================
-
-.. include:: tangential_complex_sum.inc
-
-
 Topological descriptors tools
 *****************************
 
@@ -88,6 +81,11 @@ Persistence graphical tools
 
 .. include:: persistence_graphical_tools_sum.inc
 
+Point cloud utilities
+*********************
+
+.. include:: point_cloud_sum.inc
+
 Bibliography
 ************
 
diff --git a/src/python/doc/point_cloud.rst b/src/python/doc/point_cloud.rst
new file mode 100644
index 00000000..d668428a
--- /dev/null
+++ b/src/python/doc/point_cloud.rst
@@ -0,0 +1,22 @@
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+============================
+Point cloud utilities manual
+============================
+
+File Readers
+------------
+
+.. autofunction:: gudhi.read_points_from_off_file
+
+.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file
+
+Subsampling
+-----------
+
+.. automodule:: gudhi.subsampling
+   :members:
+   :special-members:
+   :show-inheritance:
diff --git a/src/python/doc/point_cloud_sum.inc b/src/python/doc/point_cloud_sum.inc
new file mode 100644
index 00000000..85d52de7
--- /dev/null
+++ b/src/python/doc/point_cloud_sum.inc
@@ -0,0 +1,15 @@
+.. table::
+   :widths: 30 50 20
+
+   +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
+   | | :math:`(x_1, x_2, \ldots, x_d)`                              | Utilities to process point clouds: read from file, subsample, etc.     | :Author: Vincent Rouvreau                                                                                                   |
+   | | :math:`(y_1, y_2, \ldots, y_d)`                              |                                                                        |                                                                                                                             |
+   |                                                                |                                                                        | :Introduced in: GUDHI 2.0.0                                                                                                 |
+   |                                                                |                                                                        |                                                                                                                             |
+   |                                                                |                                                                        | :Copyright: MIT (`GPL v3 </licensing/>`_)                                                                                   |
+   |                                                                | Parts of this package require CGAL.                                    |                                                                                                                             |
+   |                                                                |                                                                        | :Requires: `Eigen <installation.html#eigen>`__ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`__ :math:`\geq` 4.11.0 |
+   |                                                                |                                                                        |                                                                                                                             |
+   +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
+   | * :doc:`point_cloud`                                                                                                                                                                                                                                                  |
+   +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/src/python/gudhi/off_reader.pyx b/src/python/gudhi/off_reader.pyx
index a0d5bf25..7e6d9d80 100644
--- a/src/python/gudhi/off_reader.pyx
+++ b/src/python/gudhi/off_reader.pyx
@@ -26,7 +26,7 @@ def read_points_from_off_file(off_file=''):
     :type off_file: string
 
     :returns:  The point set.
-    :rtype: vector[vector[double]]
+    :rtype: List[List[float]]
     """
     if off_file:
         if os.path.isfile(off_file):
diff --git a/src/python/gudhi/reader_utils.pyx b/src/python/gudhi/reader_utils.pyx
index d6033b86..fe1c3a2e 100644
--- a/src/python/gudhi/reader_utils.pyx
+++ b/src/python/gudhi/reader_utils.pyx
@@ -34,7 +34,7 @@ def read_lower_triangular_matrix_from_csv_file(csv_file='', separator=';'):
     :type separator: char
 
     :returns:  The lower triangular matrix.
-    :rtype: vector[vector[double]]
+    :rtype: List[List[float]]
     """
     if csv_file:
         if path.isfile(csv_file):
@@ -45,15 +45,15 @@ def read_lower_triangular_matrix_from_csv_file(csv_file='', separator=';'):
 def read_persistence_intervals_grouped_by_dimension(persistence_file=''):
     """Reads a file containing persistence intervals.
     Each line might contain 2, 3 or 4 values: [[field] dimension] birth death
-    The return value is an `map[dim, vector[pair[birth, death]]]`
-    where `dim` is an `int`, `birth` a `double`, and `death` a `double`.
+    The return value is a `dict(dim, list(tuple(birth, death)))`
+    where `dim` is an `int`, `birth` a `float`, and `death` a `float`.
     Note: the function does not check that birth <= death.
 
     :param persistence_file: A persistence file style name.
     :type persistence_file: string
 
     :returns:  The persistence pairs grouped by dimension.
-    :rtype: map[int, vector[pair[double, double]]]
+    :rtype: Dict[int, List[Tuple[float, float]]]
     """
     if persistence_file:
         if path.isfile(persistence_file):
diff --git a/src/python/gudhi/subsampling.pyx b/src/python/gudhi/subsampling.pyx
index c501d16b..f77c6f75 100644
--- a/src/python/gudhi/subsampling.pyx
+++ b/src/python/gudhi/subsampling.pyx
@@ -33,13 +33,15 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi
     The iteration starts with the landmark `starting point`.
 
     :param points: The input point set.
-    :type points: vector[vector[double]].
+    :type points: Iterable[Iterable[float]].
 
     Or
 
     :param off_file: An OFF file style name.
     :type off_file: string
 
+    And in both cases
+
     :param nb_points: Number of points of the subsample.
     :type nb_points: unsigned.
     :param starting_point: The iteration starts with the landmark `starting \
@@ -47,7 +49,7 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi
     index is chosen randomly.
     :type starting_point: unsigned.
     :returns:  The subsample point set.
-    :rtype: vector[vector[double]]
+    :rtype: List[List[float]].
     """
     if off_file:
         if os.path.isfile(off_file):
@@ -74,17 +76,19 @@ def pick_n_random_points(points=None, off_file='', nb_points=0):
     """Subsample a point set by picking random vertices.
 
     :param points: The input point set.
-    :type points: vector[vector[double]].
+    :type points: Iterable[Iterable[float]].
 
     Or
 
     :param off_file: An OFF file style name.
     :type off_file: string
 
+    And in both cases
+
     :param nb_points: Number of points of the subsample.
     :type nb_points: unsigned.
     :returns:  The subsample point set.
-    :rtype: vector[vector[double]]
+    :rtype: List[List[float]]
     """
     if off_file:
         if os.path.isfile(off_file):
@@ -103,18 +107,20 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0):
     between any two points is greater than or equal to min_squared_dist.
 
     :param points: The input point set.
-    :type points: vector[vector[double]].
+    :type points: Iterable[Iterable[float]].
 
     Or
 
     :param off_file: An OFF file style name.
     :type off_file: string
 
+    And in both cases
+
     :param min_squared_dist: Minimum squared distance separating the output \
     points.
     :type min_squared_dist: float.
     :returns:  The subsample point set.
-    :rtype: vector[vector[double]]
+    :rtype: List[List[float]]
     """
     if off_file:
         if os.path.isfile(off_file):