Update documentation (#3480)

Fixes #3476

Description of changes:
- fix broken Sphinx syntax in docstrings of private members
- remove Sphinx apidoc `-P` flag (for Sphinx >= 2.4.0)
- remove documentation of inexistent features

doc/sphinx/CMakeLists.txt

@@ -73,7 +73,6 @@ if(SPHINX_FOUND)
         COMMAND
         ${SPHINX_API_DOC_EXE}
             -f
-            -P
             -o ${SPHINX_BASE}
             ${SPHINX_PYTHON_DIR}
             ${EXCLUDE}

doc/sphinx/analysis.rst

@@ -139,51 +139,6 @@ Two arrays are returned corresponding to the normalized distribution and the bin
     >>> print(count)
     [ 1.  0.  0.  0.  0.  0.  0.  0.  0.  0.]
 
-..
-    .. _Radial density map:
-
-    Radial density map
-    ~~~~~~~~~~~~~~~~~~
-    .. todo:: This feature is not implemented
-
-    analyze radial_density_map
-
-    Returns the radial density of particles around a given axis. Parameters
-    are:
-
-    -  histogram bins in x direction.
-
-    -  histogram bins in y direction.
-
-    -  range for analysis in x direction.
-
-    -  range for analysis in y direction.
-
-    -  rotate around given axis. (x, y, or z)
-
-    -  rotate around given point.
-
-    -  only analyze beads of given types.
-
-    -  histogram bins in angle theta.
-
-    This command does not do what you might expect. Here is an overview of
-    the currently identified properties.
-
-    #. is the number of bins along the axis of rotation.
-
-    #. is the number of bins in the radial direction.
-
-    #. The center point () of the cylinder is located in the lower cap,
-       i.e., is the height of the cylinder with respect to this center
-       point.
-
-    #. The bins are distributed along starting from 0 ().
-
-    #. The seem to average with respect to the center of mass of the
-       particles in the individual bins rather than with respect to the
-       central axis, which one would think is natural.
-
 
 .. _Radial distribution function:
 
@@ -220,38 +175,6 @@ Returns the spherically averaged structure factor :math:`S(q)` of
 particles specified in ``sf_types``. :math:`S(q)` is calculated for all possible
 wave vectors :math:`\frac{2\pi}{L} \leq q \leq \frac{2\pi}{L}` up to ``sf_order``.
 
-..
-    .. _Van-Hove autocorrelation function:
-
-    Van-Hove autocorrelation function :math:`G(r,t)`
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-    .. todo:: This feature is not implemented
-
-    analyze vanhove
-
-    Returns the van Hove auto correlation function :math:`G(r,t)` and the
-    mean square displacement :math:`msd(t)` for particles of type for the
-    configurations stored in the array configs. This tool assumes that the
-    configurations stored with (see section ) are stored at equidistant time
-    intervals. :math:`G(r,t)` is calculated for each multiple of this time
-    intervals. For each time t the distribution of particle displacements is
-    calculated according to the specification given by , and . Optional
-    argument defines the maximum value of :math:`t` for which :math:`G(r,t)`
-    is calculated. If it is omitted or set to zero, maximum possible value
-    is used. If the particles perform a random walk (a normal diffusion
-    process) :math:`G(r,t)/r^2` is a Gaussian distribution for all times.
-    Deviations of this behavior hint on another diffusion process or on the
-    fact that your system has not reached the diffusive regime. In this case
-    it is also very questionable to calculate a diffusion constant from the
-    mean square displacement via the Stokes-Einstein relation.
-
-    The output corresponds to the blockfile format (see section ):
-
-    { msd { …} } { vanhove { { …} { …} } }
-
-    The :math:`G(r,t)` are normalized such that the integral over space
-    always yields :math:`1`.
-
 
 .. _Center of mass:
 
@@ -279,35 +202,6 @@ Gyration tensor
 
 Analyze the gyration tensor of particles of a given type, or of all particles in the system if no type is given. Returns a dictionary containing the squared radius of gyration, three shape descriptors (asphericity, acylindricity, and relative shape anisotropy), eigenvalues of the gyration tensor and their corresponding eigenvectors. The eigenvalues are sorted in descending order.
 
-..
-    .. _Aggregation:
-
-    Aggregation
-    ~~~~~~~~~~~
-    .. todo:: This feature is not implemented
-
-    analyze aggregation
-
-    Returns the aggregate size distribution for the molecules in the
-    molecule id range to . If any monomers in two different molecules are
-    closer than they are considered to be in the same aggregate. One can use
-    the optional parameter to specify a minimum number of contacts such that
-    only molecules having at least contacts will be considered to be in the
-    same aggregate. The second optional parameter enables one to consider
-    aggregation state of only oppositely charged particles.
-
-
-	.. _Temperature of the LB fluid:
-
-	Temperature of the LB fluid
-	~~~~~~~~~~~~~~~~~~~~~~~~~~~
-	.. todo:: This feature is not implemented
-
-	This command returns the temperature of the lattice-Boltzmann (LB)
-	fluid, see Chapter [sec:lb], by averaging over the fluid nodes. In case
-	or are compiled in and boundaries are defined, only the available fluid
-	volume is taken into account.
-
 
 .. _Pressure:
 
@@ -457,88 +351,6 @@ in :cite:`doi86a`.
 Note that the hydrodynamic radius is sometimes defined in a similar fashion but with a denominator of :math:`N^2` instead of :math:`N(N-1)` in the prefactor.
 Both versions are equivalent in the :math:`N\rightarrow \infty` limit but give numerically different values for finite polymers.
 
-..
-	.. _Internal distances:
-
-	Internal distances
-	^^^^^^^^^^^^^^^^^^
-	.. todo:: This feature is not implemented
-
-	analyze
-
-	Returns the averaged internal distances within the chains (over all
-	pairs of particles). If is used, the values are averaged over all stored
-	configurations (see section ).
-
-	{ … }
-
-	The index corresponds to the number of beads between the two monomers
-	considered (0 = next neighbors, 1 = one monomer in between, …).
-
-
-	.. _Internal distances II (specific monomer):
-
-	Internal distances II (specific monomer)
-	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-	.. todo:: This feature is not implemented
-
-	analyze
-
-	In contrast to , it does not average over the whole chain, but rather
-	takes the chain monomer at position (default: :math:`0`, the first
-	monomer on the chain) to be the reference point to which all internal
-	distances are calculated. If is used, the values will be averaged over
-	all stored configurations (see section ).
-
-	{ … }
-
-
-	.. _Bond lengths:
-
-	Bond lengths
-	^^^^^^^^^^^^
-	.. todo:: This feature is not implemented
-
-	analyze
-
-	Analyzes the bond lengths of the chains in the system. Returns its
-	average, the standard deviation, the maximum and the minimum. If you
-	want to look only at specific chains, use the optional arguments,
-	:math:`\var{chain\_start} =
-	2*\var{MPC}` and :math:`\var{n\_chains} = 1` to only include the third
-	chain's monomers. If is used, the value will be averaged over all stored
-	configurations (see section ). This function assumes linear chain
-	topology and does not check if the bonds really exist!
-
-	{ }
-
-
-	.. _Form factor:
-
-	Form factor
-	^^^^^^^^^^^
-	.. todo:: This feature is not implemented
-
-	| analyze
-
-	Computes the spherically averaged form factor of a single chain, which
-	is defined by
-
-	.. math::
-
-	   S(q) = \frac{1}{\var{chain\_length}} \sum_{i,j=1}^{\var{chain\_length}}
-		 \frac{\sin(q r_{ij})}{q r_{ij}}
-
-	of a single chain, averaged over all chains for :math:`\var{qbin}+1`
-	logarithmically spaced q-vectors :math:`\var{qmin}, \dots ,\var{qmax}`
-	where :math:`\var{qmin}>0` and :math:`\var{qmax}>\var{qmin}`. If is
-	used, the form factor will be averaged over all stored configurations
-	(see section ).
-
-	{ { } }
-
-	with :math:`q \in \{\var{qmin},\dots,\var{qmax}\}`.
-
 
 .. _Observables and correlators:
 

doc/sphinx/conf.py.in

@@ -59,7 +59,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'ESPResSo'
-copyright = '2018-2019, The ESPResSo project'
+copyright = '2018-2020, The ESPResSo project'
 author = 'C. Holm, F. Weik, R. Weeber'
 
 # The version info for the project you're documenting, acts as replacement for

doc/sphinx/constraints.rst

@@ -362,7 +362,7 @@ The region is described as a pore (lower vertical part of the "T"-shape) and a c
 
 .. _figure-slitpore:
 
-.. figure:: figures/slitpore.pdf
+.. figure:: figures/slitpore.png
    :alt: Schematic for the slitpore shape showing geometrical parameters
    :align: center
    :height: 6.00000cm
@@ -423,14 +423,19 @@ Pictured is an example constraint with a ``SpheroCylinder`` shape created with :
 
 
 :class:`espressomd.shapes.HollowConicalFrustum`
-The conical frustum shape is a hollow cone with round corners. The specific parameters
-are described in the shapes class :class:`espressomd.shapes.HollowConicalFrustum`.
+    The conical frustum shape is a hollow cone with round corners. The specific parameters
+    are described in the shapes class :class:`espressomd.shapes.HollowConicalFrustum`.
 
 .. figure:: figures/shape-conical_frustum.png
    :alt: Conical frustum shape schematic.
    :align: center
    :height: 6.00000cm
 
+.. figure:: figures/conical_frustum.png
+   :alt: Schematic for the conical frustum shape showing geometrical parameters
+   :align: center
+   :height: 6.00000cm
+
 
 For the shapes ``wall``, ``sphere``, ``cylinder``, ``rhomboid``,
 ``pore`` and ``stomatocyte``, constraints are able to be penetrated if
@@ -518,24 +523,10 @@ define nodes which are part of a boundary, please refer to :ref:`Using shapes
 as lattice-Boltzmann boundary`.
 
 
-..
-    .. _Creating a harmonic trap:
-
-    Creating a harmonic trap
-    ------------------------
-
-    .. todo:: This feature is not yet implemented.
-
-    Calculates a spring force for all particles, where the equilibrium
-    position of the spring is at and its force constant is . A more
-    flexible trap can be constructed with constraints, but this one runs on
-    the GPU.
-
 .. _External Fields:
 
-
 External Fields
---------------------------
+---------------
 
 There is a variety of external fields, which differ by how their
 values are obtained and how they couple to particles.
@@ -560,7 +551,7 @@ here.
 
 
 Interpolated Force and Potential fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The values of these fields are obtained by interpolating table data,
 which has to be provided by the user. The fields differ by how