Doc improvement robots/configurations

Author: tetov

src/compas_fab/robots/configuration.py

@@ -11,16 +11,23 @@
 
 class Configuration(object):
     """Represents the configuration of a robot based on the state of its joints.
+
     This concept is also refered to as `Joint State`.
 
-    Attributes
+    Parameters
     ----------
     values : :obj:`list` of :obj:`float`
         Joint values expressed in radians or meters, depending on the respective type.
-    types : list of :class:`compas.robots.Joint.TYPE`
+    types : list of :data:`compas.robots.Joint.SUPPORTED_TYPES`
         Joint types, e.g. a list of `compas.robots.Joint.REVOLUTE` for revolute joints.
     joint_names : :obj:`list` of :obj:`str`, optional
-        Joint names list
+        List of joint names.
+
+    Attributes
+    ----------
+    data
+    prismatic_values
+    revolute_values
 
     Examples
     --------
@@ -52,13 +59,15 @@ def __init__(self, values=None, types=None, joint_names=None):
                 len(self.values), len(self.values), len(self.types)))
 
     def __str__(self):
+        """Nicely printable representation of :class:`Configuration`."""
         v_str = ('(' + ", ".join(['%.' + self._precision] * len(self.values)) + ')') % tuple(self.values)
         if len(self.joint_names):
             return "Configuration({}, {}, {})".format(v_str, tuple(self.types), tuple(self.joint_names))
         else:
             return "Configuration({}, {})".format(v_str, tuple(self.types))
 
     def __repr__(self):
+        """Printable representation of :class:`Configuration`."""
         return self.__str__()
 
     @classmethod
@@ -92,7 +101,7 @@ def from_prismatic_and_revolute_values(cls, prismatic_values, revolute_values):
         Returns
         -------
         :class:`Configuration`
-             An instance of :class:`Configuration` instance.
+             An instance of :class:`Configuration`.
         """
         # Force iterables into lists
         prismatic_values = list(prismatic_values)
@@ -114,24 +123,33 @@ def from_data(cls, data):
         Returns
         -------
         :class:`Configuration`
-             An instance of :class:`Configuration` instance.
+             An instance of :class:`Configuration`.
         """
         config = cls()
         config.data = data
         return config
 
     def to_data(self):
-        """Return the data dictionary that represents the configuration, and from
-        which it can be reconstructed."""
+        """Get the data dictionary that represents the configuration.
+
+        This data can also be used to reconstruct the :class:`Configuration`
+        instance.
+
+        Returns
+        -------
+        :class:`dict`
+            The data representing the configuration.
+        """
         return self.data
 
     @property
     def data(self):
         """:obj:`dict` : The data representing the configuration.
 
-        By assigning a data dictionary to this property, the current data of the
-        configuration will be replaced by the data in the dict. The data getter
-        and setter should always be used in combination with each other.
+        By assigning a data dictionary to this property, the current data of
+        the configuration will be replaced by the data in the :obj:`dict`. The
+        data getter and setter should always be used in combination with each
+        other.
         """
         return {
             'values': self.values,
@@ -149,7 +167,8 @@ def data(self, data):
     def prismatic_values(self):
         """:obj:`list` of :obj:`float` : Prismatic joint values in meters.
 
-        E.g. positions on the external axis system."""
+        E.g. positions on the external axis system.
+        """
         return [v for i, v in enumerate(self.values) if self.types[i] == Joint.PRISMATIC]
 
     @property
@@ -158,6 +177,13 @@ def revolute_values(self):
         return [v for i, v in enumerate(self.values) if self.types[i] == Joint.REVOLUTE]
 
     def copy(self):
+        """Create a copy of this :class:`Configuration`.
+
+        Returns
+        -------
+        :class:`Configuration`
+            An instance of :class:`Configuration`
+        """
         cls = type(self)
         return cls(self.values[:], self.types[:], self.joint_names[:])
 
@@ -168,8 +194,8 @@ def scale(self, scale_factor):
 
         Parameters
         ----------
-        scale_factor : float
-            Scale factor
+        scale_factor : :class:`float`
+            Scale factor.
 
         Returns
         -------
@@ -185,13 +211,13 @@ def scale(self, scale_factor):
         self.values = values_scaled
 
     def scaled(self, scale_factor):
-        """Returns a scaled copy of this configuration.
+        """Return a scaled copy of this configuration.
 
         Only scalable joints are scaled, i.e. planar and prismatic joints.
 
         Parameters
         ----------
-        scale_factor : float
+        scale_factor : :class:`float`
             Scale factor
 
         Returns