Fix various links for sphinx

and some minor doc changes along the way.
(why were we documenting a hasse diagram that doesn't exist?)

8 files changed, 32 insertions, 33 deletions

diff --git a/src/python/doc/alpha_complex_user.rst b/src/python/doc/alpha_complex_user.rst
index f9662a6d..950db3cd 100644
--- a/src/python/doc/alpha_complex_user.rst
+++ b/src/python/doc/alpha_complex_user.rst
@@ -9,19 +9,19 @@ Definition
 
 .. include:: alpha_complex_sum.inc
 
-Alpha_complex is constructing a :doc:`Simplex_tree <simplex_tree_ref>` using
+`AlphaComplex` is constructing a :doc:`SimplexTree <simplex_tree_ref>` 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 :math:`\alpha`, the complex is a Delaunay complex.
+When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha`, the complex is a Delaunay complex (with special filtration values).
 
 Example from points
 -------------------
 
-This example builds the Delaunay triangulation from the given points, and initializes the alpha complex with it:
+This example builds the alpha-complex from the given points:
 
 .. testcode::
 
@@ -139,15 +139,16 @@ 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.
+We fix that up by calling :func:`~gudhi.SimplexTree.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()`
-in the `C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_). Note that this does not provide any kind
-of speed-up, since we always first build the full filtered complex, so it is recommended not to use `max_alpha_square`.
+The simplex tree is pruned from the given maximum alpha squared value (cf.
+:func:`~gudhi.SimplexTree.prune_above_filtration`). Note that this does not provide any kind
+of speed-up, since we always first build the full filtered complex, so it is recommended not to use
+:paramref:`~gudhi.AlphaComplex.create_simplex_tree.max_alpha_square`.
 In the following example, a threshold of 59 is used.
 
 
diff --git a/src/python/doc/conf.py b/src/python/doc/conf.py
index 64d9cba1..3cc5d1d6 100755
--- a/src/python/doc/conf.py
+++ b/src/python/doc/conf.py
@@ -41,6 +41,7 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinxcontrib.bibtex',
+    'sphinx_paramlinks',
 ]
 
 todo_include_todos = True
diff --git a/src/python/doc/representations.rst b/src/python/doc/representations.rst
index c870f834..b3131a25 100644
--- a/src/python/doc/representations.rst
+++ b/src/python/doc/representations.rst
@@ -10,7 +10,7 @@ Representations manual
 
 This module, originally named sklearn_tda, aims at bridging the gap between persistence diagrams and machine learning tools, in particular scikit-learn. It provides tools, using the scikit-learn standard interface, to compute distances and kernels on diagrams, and to convert diagrams into vectors.
 
-A diagram is represented as a numpy array of shape (n,2), as can be obtained from :func:`gudhi.SimplexTree.persistence_intervals_in_dimension` for instance. Points at infinity are represented as a numpy array of shape (n,1), storing only the birth time.
+A diagram is represented as a numpy array of shape (n,2), as can be obtained from :func:`~gudhi.SimplexTree.persistence_intervals_in_dimension` for instance. Points at infinity are represented as a numpy array of shape (n,1), storing only the birth time.
 
 A small example is provided
 
diff --git a/src/python/doc/rips_complex_user.rst b/src/python/doc/rips_complex_user.rst
index 3f6b960d..a8659542 100644
--- a/src/python/doc/rips_complex_user.rst
+++ b/src/python/doc/rips_complex_user.rst
@@ -40,12 +40,12 @@ A vertex name corresponds to the index of the point in the given range (aka. the
 On this example, as edges (4,5), (4,6) and (5,6) are in the complex, simplex (4,5,6) is added with the filtration value
 set with :math:`max(filtration(4,5), filtration(4,6), filtration(5,6))`. And so on for simplex (0,1,2,3).
 
-If the `RipsComplex` interfaces are not detailed enough for your need, please refer to rips_persistence_step_by_step.cpp
-C++ example, where the graph construction over the Simplex_tree is more detailed.
+If the :doc:`RipsComplex <rips_complex_ref>` interfaces are not detailed enough for your need, please refer to
+rips_persistence_step_by_step.cpp C++ example, where the graph construction over the Simplex_tree is more detailed.
 
 A Rips complex can easily become huge, even if we limit the length of the edges
 and the dimension of the simplices. One easy trick, before building a Rips
-complex on a point cloud, is to call `sparsify_point_set` which removes points
+complex on a point cloud, is to call :func:`~gudhi.sparsify_point_set` which removes points
 that are too close to each other. This does not change its persistence diagram
 by more than the length used to define "too close".
 
@@ -57,7 +57,7 @@ a :math:`\frac{1}{1-\varepsilon}`-interleaving, although in practice the
 error is usually smaller.  A more intuitive presentation of the idea is
 available in :cite:`cavanna15geometric`, and in a video
 :cite:`cavanna15visualizing`. Passing an extra argument `sparse=0.3` at the
-construction of a `RipsComplex` object asks it to build a sparse Rips with
+construction of a :class:`~gudhi.RipsComplex` object asks it to build a sparse Rips with
 parameter :math:`\varepsilon=0.3`, while the default `sparse=None` builds the
 regular Rips complex.
 
@@ -69,7 +69,7 @@ Example from a point cloud
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This example builds the neighborhood graph from the given points, up to max_edge_length.
-Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it.
+Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it.
 
 Finally, it is asked to display information about the simplicial complex.
 
@@ -128,7 +128,7 @@ Example from OFF file
 
 This example builds the :doc:`RipsComplex <rips_complex_ref>` from the given
 points in an OFF file, and max_edge_length value.
-Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it.
+Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it.
 
 Finally, it is asked to display information about the Rips complex.
 
@@ -178,7 +178,7 @@ Example from a distance matrix
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This example builds the one skeleton graph from the given distance matrix, and max_edge_length value.
-Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it.
+Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it.
 
 Finally, it is asked to display information about the simplicial complex.
 
@@ -233,7 +233,7 @@ Example from csv file
 
 This example builds the :doc:`RipsComplex <rips_complex_ref>` from the given
 distance matrix in a csv file, and max_edge_length value.
-Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it.
+Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it.
 
 Finally, it is asked to display information about the Rips complex.
 
@@ -286,7 +286,7 @@ Example from  a correlation matrix
 Analogously to the case of distance matrix, Rips complexes can be also constructed based on correlation matrix.
 Given a correlation matrix M, comportment-wise 1-M is a distance matrix.
 This example builds the one skeleton graph from the given corelation matrix and threshold value.
-Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it.
+Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it.
 
 Finally, it is asked to display information about the simplicial complex.
 
@@ -307,7 +307,7 @@ Finally, it is asked to display information about the simplicial complex.
                                 [0.01, 0.01, 0.72, 1., 0.7],
                                 [0.89, 0.61, 0.03, 0.7, 1.]], float)
 
-    distance_matrix = np.ones((correlation_matrix.shape),float) - correlation_matrix
+    distance_matrix = 1 - correlation_matrix
     rips_complex = gudhi.RipsComplex(distance_matrix=distance_matrix, max_edge_length=1.0)
 
     simplex_tree = rips_complex.create_simplex_tree(max_dimension=1)
@@ -342,6 +342,7 @@ until dimension 1 - one skeleton graph in other words), the output is:
     [1, 3] -> 0.99
 
 .. note::
-    As persistence diagrams points will be under the diagonal,
+    If you compute the persistence diagram and convert distances back to correlation values,
+    points in the persistence diagram will be under the diagonal, and
     bottleneck distance and persistence graphical tool will not work properly,
     this is a known issue.
diff --git a/src/python/doc/simplex_tree_user.rst b/src/python/doc/simplex_tree_user.rst
index aebeb29f..3df7617f 100644
--- a/src/python/doc/simplex_tree_user.rst
+++ b/src/python/doc/simplex_tree_user.rst
@@ -23,13 +23,9 @@ scheme.
 Implementation
 --------------
 
-There are two implementation of complexes. The first on is the Simplex_tree data structure.
-The simplex tree is an efficient and flexible data structure for representing general (filtered) simplicial complexes.
-The data structure is described in :cite`boissonnatmariasimplextreealgorithmica`.
-
-The second one is the Hasse_complex. The Hasse complex is a data structure representing explicitly all co-dimension 1
-incidence relations in a complex. It is consequently faster when accessing the boundary of a simplex, but is less
-compact and harder to construct from scratch.
+The :class:`simplex tree<gudhi.SimplexTree>` is an efficient and flexible data structure for representing general
+(filtered) simplicial complexes.
+The data structure is described in :cite:`boissonnatmariasimplextreealgorithmica`.
 
 Example
 -------
diff --git a/src/python/doc/tangential_complex_user.rst b/src/python/doc/tangential_complex_user.rst
index ebfe1e29..852cf5b6 100644
--- a/src/python/doc/tangential_complex_user.rst
+++ b/src/python/doc/tangential_complex_user.rst
@@ -107,12 +107,12 @@ inconsistencies, but is not guaranteed to succeed.
 
 Output
 ^^^^^^
-The result of the computation is exported as a Simplex_tree. It is the union of
+The result of the computation is exported as a :class:`~gudhi.SimplexTree`. It is the union of
 the stars of all the input points. A vertex in the Simplex Tree is the index of
 the point in the range provided by the user. The point corresponding to a
-vertex can also be obtained through the Tangential_complex::get_point function.
+vertex can also be obtained through the :func:`gudhi.TangentialComplex.get_point` function.
 Note that even if the positions of the points are perturbed, their original
-positions are kept (e.g. Tangential_complex::get_point returns the original
+positions are kept (e.g. :func:`~gudhi.TangentialComplex.get_point` returns the original
 position of the point).
 
 The result can be obtained after the computation of the Tangential complex
diff --git a/src/python/doc/witness_complex_user.rst b/src/python/doc/witness_complex_user.rst
index 40e94134..45ba5b3b 100644
--- a/src/python/doc/witness_complex_user.rst
+++ b/src/python/doc/witness_complex_user.rst
@@ -47,7 +47,7 @@ which leads to definitions of **weak relaxed witness complex** (or just relaxed
 In particular case of 0-relaxation, weak complex corresponds to **witness complex** introduced in
 :cite:`de2004topological`, whereas 0-relaxed strong witness complex consists of just vertices and is not very
 interesting. Hence for small relaxation weak version is preferable.
-However, to capture the homotopy type (for example using Gudhi::persistent_cohomology::Persistent_cohomology) it is
+However, to capture the homotopy type (for example using :func:`gudhi.SimplexTree.persistence`) it is
 often necessary to work with higher filtration values. In this case strong relaxed witness complex is faster to compute
 and offers similar results.
 
@@ -69,7 +69,7 @@ The construction of the Euclidean versions of complexes follow the same scheme:
 
 In the non-Euclidean classes, the lists of nearest landmarks are supposed to be given as input.
 
-The constructors take on the steps 1 and 2, while the function 'create_complex' executes the step 3.
+The constructors take on the steps 1 and 2, while the function :func:`!create_complex` executes the step 3.
 
 Constructing weak relaxed witness complex from an off file
 ----------------------------------------------------------
diff --git a/src/python/gudhi/tangential_complex.pyx b/src/python/gudhi/tangential_complex.pyx
index b7678f4d..f4c8b079 100644
--- a/src/python/gudhi/tangential_complex.pyx
+++ b/src/python/gudhi/tangential_complex.pyx
@@ -91,7 +91,7 @@ cdef class TangentialComplex:
         Raises:
             ValueError: In debug mode, if the computed star dimension is too
                 low. Try to set a bigger maximal edge length value with
-                :func:`~gudhi.Tangential_complex.set_max_squared_edge_length`
+                :meth:`set_max_squared_edge_length`
                 if this happens.
         """
         self.thisptr.compute_tangential_complex()
@@ -166,7 +166,7 @@ cdef class TangentialComplex:
         :type max_squared_edge_length: double
 
         If the maximal edge length value is too low
-        :func:`~gudhi.Tangential_complex.compute_tangential_complex`
+        :meth:`compute_tangential_complex`
         will throw an exception in debug mode.
         """
         self.thisptr.set_max_squared_edge_length(max_squared_edge_length)