Update docstrings for deprecated functions (#207)

* Add `deprecate` function

* Deprecate `sinkhorn` and `gromov_wasserstein`

* Deprecate `solve`

* [ci skip] Add deprecation warnings in docstrings

src/ott/solvers/linear/sinkhorn.py

@@ -935,6 +935,12 @@ def sinkhorn(
 ):
   r"""Solve regularized OT problem using Sinkhorn iterations.
 
+  .. note::
+
+    This function has been deprecated and will be removed in ``0.3.2`` release.
+    Please use the :class:`~ott.solvers.linear.sinkhorn.Sinkhorn` solver
+    instead.
+
   The Sinkhorn algorithm is a fixed point iteration that solves a regularized
   optimal transport (reg-OT) problem between two measures.
   The optimization variables are a pair of vectors (called potentials, or

src/ott/solvers/quadratic/gromov_wasserstein.py

@@ -474,6 +474,13 @@ def gromov_wasserstein(
 ) -> GWOutput:
   """Solve a Gromov Wasserstein problem.
 
+  .. note::
+
+    This function has been deprecated and will be removed in ``0.3.2`` release.
+    Please use the
+    :class:`~ott.solvers.quadratic.gromov_wasserstein.GromovWasserstein`
+    solver instead.
+
   Wrapper that instantiates a quadratic problem (possibly with linear term
   if the problem is fused) and calls a solver to output a solution.
 

src/ott/tools/transport.py

@@ -92,6 +92,11 @@ def solve(
 ) -> Transport:
   """Generic interface to transport problem.
 
+  .. note:
+
+    This function has been deprecated and will be removed in ``0.3.2`` release.
+    Please use :mod:`ott.solvers` module directly.
+
   The geometries can be passed as arrays, geometry.Geometry or directly as a
   problem. The solver is passed via kwargs.