improve docstrings (slightly)

Author: hungpham2511

README.md

@@ -9,21 +9,12 @@ TOPP-RA is a library for time-parameterizing robot trajectories subject to kinem
 
 If you use this library for your research, please reference the accompanying paper [«A new approach to Time-Optimal Path Parameterization based on Reachability Analysis»](https://arxiv.org/abs/1707.07239), *IEEE Transactions on Robotics*, vol. 34(3), pp. 645–659, 2018.
 
+For documentations and some tutorials, see [TOPP-RA's documentation](https://hungpham2511.github.io/toppra/).
+
 # Installation
 ## Basic functionality (robotic manipulators)
 
 
-Install
-[qpOASES](https://projects.coin-or.org/qpOASES/wiki/QpoasesInstallation) by
-following the steps below:
-``` shell
-git clone https://github.com/hungpham2511/qpOASES
-cd qpOASES/ && mkdir bin && make
-cd interfaces/python/
-pip install cython
-python setup.py install --user
-```
-
 Finally, install `toppra` with
 ``` sh
 git clone https://github.com/hungpham2511/toppra

docs/source/index.rst

@@ -41,6 +41,11 @@ parametrize trajectories subject to velocity and acceleration
 constraints. Some advanced functionalities require `openrave`, `cvxpy`
 and so on. See :doc:`installation` for the full instruction.
 
+.. toctree::
+   :maxdepth: 2
+
+   installation
+
 Tutorials
 ~~~~~~~~~~~~~~~~~~
 .. toctree::

docs/source/tutorials/2_can_linear_constraints.rst

@@ -1,12 +1,12 @@
-2: Canonical Linear Constraint
-========================================
+2: Simple [1]_ Second-Order Constraint
+====================================
 
 TOPP-RA *can not* account for arbitrary constraint; it can only handle
 those constraints of certain kinds. One class of constraints TOPP-RA
 supports is Second-Order constraint.
 
 This class of constraint is quite general.  Commonly found constraints
-such as joint acceleration, tool tip Cartesian acceleration,
+such as joint acceleration [2]_, tool tip Cartesian acceleration,
 interaction force on the robot base, are all Second-Order constraints.
 
 Background
@@ -177,6 +177,14 @@ Download the example given this tutorial here
 :download:`cartesian_accel.py <../../../examples/cartesian_accel.py>`.
 
 
+.. [1] The form of Second-Order constraint presented in this tutorial
+       is not the most general, hence, they are simple.
 
+.. [2] Cartesian velocity constraint, as well as joint velocity
+       constraint, are not Second-Order Constraint. They are
+       First-Order constraints. These constraints will be treated in
+       near future. For now, see how
+       :class:`toppra.constraint.JointVelocityConstraint` is
+       implemented.
 
 

setup.py

@@ -33,7 +33,6 @@
                   extra_compile_args=['-O1'],
                   include_dirs=[np.get_include()])
 
-
 EXTENSIONS = [ext_1, ext_2]
 
 if __name__ == "__main__":

toppra/__init__.py

@@ -16,5 +16,6 @@
 from .planning_utils import retime_active_joints_kinematics, create_rave_torque_path_constraint
 import constraint as constraint
 import algorithm as algorithm
+import solverwrapper as solverwrapper
 
 setup_logging()

toppra/algorithm/reachabilitybased/time_optimal_algorithm.py

@@ -6,15 +6,22 @@
 
 
 class TOPPRA(ReachabilityAlgorithm):
-    """ The Time-Optimal Path Parameterization based on Reachability Analysis algorithm.
+    """Time-Optimal Path Parameterization based on Reachability
+    Analysis (TOPPRA).
 
     Parameters
     ----------
-    constraint_list: list of Constraint
-    path: Interpolator
+    constraint_list: :class:`~toppra.constraint.Constraint` list
+        List of constraints to which the robotic system is subjected to.
+    path: :class:`~toppra.Interpolator`
+        Input geometric path.
     gridpoints: array, optional
+        Gridpoints for discretization of the geometric path. The start
+        and end points must agree with the geometric path's domain.
     solver_wrapper: str, optional
-        Name of the solver to use.
+        Name of the solver wrapper to use.
+        See :class:`toppra.solverwrapper.hotqpOASESSolverWrapper`,
+        :class:`toppra.solverwrapper.seidelWrapper`
 
     """
 

toppra/constraint/canonical_conic.py

@@ -52,17 +52,20 @@ class RobustCanonicalLinearConstraint(CanonicalConicConstraint):
     in a centered ellipsoid:
 
     .. math::
-        [\Delta a[i, j], \Delta b[i, j], \Delta c[i, j]]^\top = diag(ru, rx, rc) \mathbf e,
+
+        [\Delta a[i, j], \Delta b[i, j], \Delta c[i, j]]^\\top = diag(ru, rx, rc) \mathbf e,
 
     where \|\mathbf e\|_2 \leq 1.
 
     Parameters
     ----------
-    cnst: `CanonicalLinearConstraint`
-        The base CanonicalLinearConstraint.
+    cnst: :class:`~toppra.constraint.CanonicalLinearConstraint`
+        The base constraint to robustify.
     ellipsoid_axes_lengths: (3,)array
         Lengths of the axes of the perturbation ellipsoid. Must all be
         non-negative.
+    discretization_scheme: :class:`~.constraint.DiscretizationType`
+        Constraint discretization scheme to use.
     """
     def __init__(self, cnst, ellipsoid_axes_lengths, discretization_scheme=DiscretizationType.Collocation):
         super(RobustCanonicalLinearConstraint, self).__init__()

toppra/constraint/constraint.py

@@ -10,6 +10,14 @@ class ConstraintType(Enum):
 
 
 class DiscretizationType(Enum):
+    """Enum to mark different Discretization Scheme for constraint. 
+
+    1. `Collocation`: smaller problem size, but lower accuracy.
+    2. `Interplation`: larger problem size, but higher accuracy.
+
+    In general, the difference in speed is not too large. Should use
+    Interpolation if possible.
+    """
     Collocation = 0
     Interpolation = 1
 

toppra/solverwrapper/cy_seidel_solverwrapper.pyx

@@ -1,3 +1,4 @@
+# cython: embedsignature=True
 import numpy as np
 cimport numpy as np
 from libc.math cimport abs, pow, isnan
@@ -352,6 +353,20 @@ cdef LpSol cy_solve_lp2d(double[:] v, double[:] a, double[:] b, double[:] c, dou
     return sol
 
 cdef class seidelWrapper:
+    """ A solver wrapper that implements Seidel's LP algorithm.
+
+    This wrapper can only be used if there is only Canonical Linear
+    Constraints.
+
+    Parameters
+    ----------
+    constraint_list: list of :class:`.Constraint`
+        The constraints the robot is subjected to.
+    path: :class:`.Interpolator`
+        The geometric path.
+    path_discretization: array
+        The discretized path positions.
+    """
     cdef:
         list constraints, _params
         unsigned int N, nV, nC, nCons
@@ -367,6 +382,20 @@ cdef class seidelWrapper:
 
     # @cython.profile(True)
     def __init__(self, list constraint_list, path, path_discretization):
+        """ A solver wrapper that implements Seidel's LP algorithm.
+
+        This wrapper can only be used if there is only Canonical Linear
+        Constraints.
+
+        Parameters
+        ----------
+        constraint_list: list of :class:`.Constraint`
+            The constraints the robot is subjected to.
+        path: :class:`.Interpolator`
+            The geometric path.
+        path_discretization: array
+            The discretized path positions.
+        """
         self.constraints = constraint_list
         self.path = path
         path_discretization = np.array(path_discretization)
@@ -485,7 +514,7 @@ cdef class seidelWrapper:
                            & x_{min} \leq x \leq x_{max}             \\\\
                            & x_{next, min} \leq x + 2 \Delta_i u \leq x_{next, max},
 
-        NOTE: if x_min == x_max, one can solve an LP instead of a 2D
+        TODO if x_min == x_max, one can solve an LP instead of a 2D
         LP. This optimization is currently not implemented.
 
         Parameters

toppra/solverwrapper/ecos_solverwrapper.py

@@ -11,8 +11,20 @@
 
 
 class ecosWrapper(SolverWrapper):
-    """ A wrapper that handles linear and conic-quadratic constraints using ECOS.
-
+    """A solver wrapper that handles linear and conic-quadratic constraints using ECOS.
+
+    :class:`ecosWrapper` and :class:`cvxpyWrapper` are the only
+    wrappers that can handle conic-quadratic constraints, which are
+    necessary to compute robust path parameterization.
+
+    Attributes
+    ----------
+    constraints : list of `Constraint`
+        Constraints on the robot system.
+    path : Interpolator
+        The geometric path to be time-parametrized.
+    path_discretization: array
+        The discretization grid use to discretize the geometric path.
 
     """
     def __init__(self, constraint_list, path, path_discretization):