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

7 files changed, 69 insertions, 38 deletions

diff --git a/src/python/doc/reader_utils_ref.rst b/src/python/doc/diagram_readers_ref.rst
index f3ecebad..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_off
-
-.. 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..9513deb0 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,14 +58,10 @@ Persistence cohomology
 
 .. include:: persistent_cohomology_sum.inc
 
-Manifold reconstruction
-***********************
-
-Tangential complex
-==================
-
-.. include:: tangential_complex_sum.inc
+Point cloud utilities
+*********************
 
+.. include:: point_cloud_sum.inc
 
 Topological descriptors tools
 *****************************
diff --git a/src/python/doc/point_cloud.rst b/src/python/doc/point_cloud.rst
new file mode 100644
index 00000000..6a74d253
--- /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_off
+
+.. 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..cefcf1c8
--- /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 225e981c..e45356be 100644
--- a/src/python/gudhi/off_reader.pyx
+++ b/src/python/gudhi/off_reader.pyx
@@ -26,7 +26,7 @@ def read_off(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 6994c4f9..5a756e4b 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,7 +45,7 @@ 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]]]`
+    The return value is a `dict(dim, list(tuple(birth, death)))`
     where `dim` is an `int`, `birth` a `double`, and `death` a `double`.
     Note: the function does not check that birth <= death.
 
@@ -53,7 +53,7 @@ def read_persistence_intervals_grouped_by_dimension(persistence_file=''):
     :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 e0cd1348..04f66219 100644
--- a/src/python/gudhi/subsampling.pyx
+++ b/src/python/gudhi/subsampling.pyx
@@ -33,7 +33,7 @@ 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: list(list(float)).
 
     Or
 
@@ -47,7 +47,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,7 +74,7 @@ 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: list(list(float)).
 
     Or
 
@@ -84,7 +84,7 @@ def pick_n_random_points(points=None, off_file='', nb_points=0):
     :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,7 +103,7 @@ 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: list(list(float)).
 
     Or
 
@@ -114,7 +114,7 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0):
     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):