Cleanup Sphinx documentation

Fix incorrect Sphinx reST syntax and correct typos.

src/python/espressomd/accumulators.py

@@ -26,18 +26,18 @@ class MeanVarianceCalculator(ScriptInterfaceHelper):
 
     Parameters
     ----------
-    obs : Instance of :class:`espressomd.observables.Observable`.
+    obs : :class:`espressomd.observables.Observable`
     delta_N : :obj:`int`
         Number of timesteps between subsequent samples for the auto update mechanism.
 
     Methods
     -------
-    update
+    update()
         Update the accumulator (get the current values from the observable).
-    get_mean
+    get_mean()
         Returns the samples mean values of the respective observable with which the
         accumulator was initialized.
-    get_variance
+    get_variance()
         Returns the samples variance for the observable.
 
     """
@@ -58,17 +58,17 @@ class TimeSeries(ScriptInterfaceHelper):
 
     Parameters
     ----------
-    obs : Instance of :class:`espressomd.observables.Observable`.
+    obs : :class:`espressomd.observables.Observable`
     delta_N : :obj:`int`
         Number of timesteps between subsequent samples for the auto update mechanism.
 
     Methods
     -------
-    update
+    update()
         Update the accumulator (get the current values from the observable).
-    time_series
+    time_series()
         Returns the recorded values of the observable.
-    clear
+    clear()
         Clear the data
 
     """

src/python/espressomd/cluster_analysis.py

@@ -21,27 +21,24 @@
 @script_interface_register
 class Cluster(ScriptInterfaceHelper):
 
-    """Class representing a cluster of particles
+    """Class representing a cluster of particles.
 
     Methods
     -------
     particle_ids()
         Returns list of particle ids in the cluster
 
-    particles()
-        Returns an instance of ParticleSlice containing the particles in the cluster
-
     size()
         Returns the number of particles in the cluster
 
     center_of_mass()
-        center of mass of the cluster
+        Center of mass of the cluster
 
     longest_distance()
         Longest distance between any combination of two particles in the cluster
 
     fractal_dimension(dr=None)
-        estimates the cluster's fractal dimension by fitting the number of
+        Estimates the cluster's fractal dimension by fitting the number of
         particles :math:`n` in spheres of growing radius around the center of mass
         to :math:`c*r_g^d`, where :math:`r_g` is the radius of gyration of the
         particles within the sphere, and :math:`d` is the fractal dimension.
@@ -52,13 +49,14 @@ class Cluster(ScriptInterfaceHelper):
 
         Parameters
         ----------
-        dr:
+        dr: :obj:`float`
             Minimum increment for the radius of the spheres.
 
         Returns
         -------
         :obj:`tuple`:
-            Fractal_dimension, mean_square_residual.
+            Fractal dimension and mean square residual.
+
     """
     _so_name = "ClusterAnalysis::Cluster"
     _so_bind_methods = ("particle_ids", "size", "longest_distance",
@@ -67,6 +65,14 @@ class Cluster(ScriptInterfaceHelper):
     _so_creation_policy = "LOCAL"
 
     def particles(self):
+        """
+        Get particles in the cluster.
+
+        Returns
+        -------
+        :class:`espressomd.particle_data.ParticleSlice`
+
+        """
         return ParticleSlice(self.particle_ids())
 
 
@@ -75,9 +81,9 @@ class ClusterStructure(ScriptInterfaceHelper):
 
     """Cluster structure of a simulation system, and access to cluster analysis
 
-    Attributes
+    Parameters
     ----------
-    pair_criterion: classes derived from ``_PairCriterion``
+    pair_criterion: :class:`espressomd.pair_criteria._PairCriterion`
         Criterion to decide whether two particles are neighbors.
 
     """
@@ -117,18 +123,25 @@ def cluster_ids(self):
         return self.call_method("cluster_ids")
 
     def cid_for_particle(self, p):
-        """Returns cluster id for the particle (passed as ParticleHandle or particle id)"""
+        """Returns cluster id for the particle.
+
+        Parameters
+        ----------
+        p : :obj:`espressomd.particle_data.ParticleHandle` or :obj:`int` containing the particle id
+            Particle.
+
+        """
         if isinstance(p, ParticleHandle):
             return self.call_method("cid_for_particle", pid=p.id)
         if isinstance(p, int):
             return self.call_method("cid_for_particle", pid=p)
-        else:
-            raise TypeError(
-                "The particle has to be passed as instance of Particle handle or as an integer particle id")
+        raise TypeError(
+            "The particle has to be passed as instance of ParticleHandle or as an integer particle id")
 
     @property
     def clusters(self):
-        """Gives access to the clusters in the cluster structure via an instance of :any:`Clusters`."""
+        """Gives access to the clusters in the cluster structure via an
+        instance of :class:`Clusters`."""
         return self._clusters
 
 
@@ -138,13 +151,14 @@ class Clusters:
 
     Access is as follows:
 
-    * Number of clusters: len(clusters)
-    * Access a cluster via its id: clusters[id]
-    * Iterate over clusters::
+    * number of clusters: ``len(clusters)``
+    * access a cluster via its id: ``clusters[id]``
+    * iterate over clusters::
 
           for c in clusters:
 
-      where c will be a tuple containing the cluster id and the cluster object
+      where ``c`` will be a tuple containing the cluster id and the cluster object.
+
     """
 
     def __init__(self, cluster_structure):

src/python/espressomd/pair_criteria.py

@@ -48,11 +48,13 @@ class DistanceCriterion(_PairCriterion):
     """Pair criterion returning true, if particles are closer than a cutoff.
     Periodic boundaries are treated via minimum image convention.
 
-    The following parameters can be passed to the constructor, changed via set_params()
-    and retrieved via get_params()
+    The following parameters can be passed to the constructor, changed via
+    ``set_params()`` and retrieved via ``get_params()``.
 
+    Parameters
+    ----------
     cut_off : :obj:`float`
-        distance cut off for the criterion
+        distance cutoff for the criterion
     """
     _so_name = "PairCriteria::DistanceCriterion"
     _so_creation_policy = "LOCAL"
@@ -61,16 +63,19 @@ class DistanceCriterion(_PairCriterion):
 @script_interface_register
 class EnergyCriterion(_PairCriterion):
 
-    """Pair criterion returning true, if the short range energy between the particles is >= the cutoff
+    """Pair criterion returning true, if the short range energy between the
+    particles is superior or equal to the cutoff.
 
-    Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions,
-    but not the long range part.
+    Be aware that the short range energy contains the short range part of
+    dipolar and electrostatic interactions, but not the long range part.
 
-    The following parameters can be passed to the constructor, changed via set_params()
-    and retrieved via get_params()
+    The following parameters can be passed to the constructor, changed via
+    ``set_params()`` and retrieved via ``get_params()``.
 
+    Parameters
+    ----------
     cut_off : :obj:`float`
-        energy cut off for the criterion
+        energy cutoff for the criterion
     """
     _so_name = "PairCriteria::EnergyCriterion"
     _so_creation_policy = "LOCAL"
@@ -81,9 +86,11 @@ class BondCriterion(_PairCriterion):
 
     """Pair criterion returning true, if a pair bond of given type exists between them
 
-    The following parameters can be passed to the constructor, changed via set_params()
-    and retrieved via get_params()
+    The following parameters can be passed to the constructor, changed via
+    ``set_params()`` and retrieved via ``get_params()``.
 
+    Parameters
+    ----------
     bond_type : :obj:`int`
         numeric type of the bond
     """

src/python/espressomd/particle_data.pyx

@@ -1416,7 +1416,8 @@ cdef class ParticleHandle:
 
         Parameters
         ----------
-        _bond : bond to be deleted
+        _bond :
+            bond to be deleted
 
         See Also
         --------

src/python/espressomd/polymer.pyx

@@ -180,14 +180,14 @@ def setup_diamond_polymer(system=None, bond=None, MPC=0,
 
     Parameters
     ----------
-    system : instance of :obj:`espressomd.system.System`, required
+    system : :class:`espressomd.system.System`, required
         System to which the particles will be added.
-    bond : instance of :obj:`espressomd.interactions.BondedInteraction`, required if ``no_bonds == False``
+    bond : :class:`espressomd.interactions.BondedInteraction`, required if ``no_bonds == False``
         The bond to be created between monomers. Should be compatible with the 
         spacing ``system.box_l[0]*(0.25 * sqrt(3))/(MPC + 1)`` between monomers.
     no_bonds : :obj:`bool`, optional
         If True, the particles will only be placed in the system but not connected by bonds. 
-        In that case, the `bond` argument can be omitted. Defaults to ``False``.
+        In that case, the ``bond`` argument can be omitted. Defaults to ``False``.
     MPC : :obj:`int`, optional
         Monomers per chain, where chain refers to the connection 
         between the 8 lattice nodes of the diamond lattice.

src/python/espressomd/shapes.py

@@ -259,7 +259,7 @@ class HollowConicalFrustum(Shape, ScriptInterfaceHelper):
     r2: :obj:`float`
         Radius r2.
     length: :obj:`float`
-        Length of the conical frustum along `axis`.
+        Length of the conical frustum along ``axis``.
     axis: (3,) array_like of :obj:`float`
         Symmetry axis.
     center: (3,) array_like of :obj:`float`

src/python/espressomd/utils.pyx

@@ -43,7 +43,8 @@ cdef List[int] create_int_list_from_python_object(obj):
 
     Parameters
     ----------
-    obj : python object which supports subscripts
+    obj :
+        python object which supports subscripts
 
     """
     cdef List[int] il
@@ -302,7 +303,8 @@ def is_valid_type(value, t):
 
 
 def requires_experimental_features(reason):
-    """Class decorator which makes instantiation conditional on EXPERIMENTAL_FEATURES being defined in myconfig.hpp."""
+    """Class decorator which makes instantiation conditional on
+    ``EXPERIMENTAL_FEATURES`` being defined in myconfig.hpp."""
 
     def exception_raiser(self, *args, **kwargs):
         raise Exception(