DOC: redo backticks in docstrings

Since too many back-ticked words clutter the online documentation
as well as the raw documentation in code, backticks were removed for
the following notions:

- Standard "basic" Python types like int, float, list, dict etc.
- The 'element' notion due to the unresolvable conflict with the method
  of the same name

Single backticks are kept for

- Less standard Python concepts like sequence, callable
- External notions and classes like array-like and numpy.ndarray

Double backticks were added (to highlight them) for

- Parameter names in text
- Values that are not numbers, e.g. (3,) for shape
- Words that match words in standard English, e.g. True, False, None

odl/deform/linearized.py

@@ -195,7 +195,7 @@ def derivative(self, displacement):
 
         Parameters
         ----------
-        displacement : `domain` element-like
+        displacement : `domain` `element-like`
             Point at which the derivative is computed.
 
         Returns

odl/discr/diff_ops.py

@@ -65,7 +65,7 @@ def __init__(self, space, axis=0, method='forward', pad_mode=None,
         method : {'central', 'forward', 'backward'}, optional
             Finite difference method which is used in the interior of the
             domain of ``f``.
-        pad_mode : {'constant', 'symmetric', 'periodic', None}, optional
+        pad_mode : {'constant', 'symmetric', 'periodic', ``None``}, optional
 
             'constant' : Pads values outside the domain of ``f`` with a
             constant value given by ``pad_const``.
@@ -75,16 +75,15 @@ def __init__(self, space, axis=0, method='forward', pad_mode=None,
 
             'periodic' : Pads with the values from the other side of the array.
 
-            If None is given, one-sided forward or backward differences
-            are used at the boundary.
+            ``None`` : Use one-sided forward or backward differences at
+            the boundary.
 
         pad_const : float, optional
             For ``pad_mode == 'constant'``, ``f`` assumes
             ``pad_const`` for indices outside the domain of ``f``
         edge_order : {1, 2}, optional
-            Edge-order accuracy at the boundaries if no padding is used. If
-            None the edge-order accuracy at endpoints corresponds to the
-            accuracy in the interior.
+            Edge-order accuracy at the boundaries if no padding is used.
+            Default: Same order as in the interior.
         """
         if not isinstance(space, DiscreteLp):
             raise TypeError('`space` {!r} is not a DiscreteLp instance'
@@ -686,7 +685,7 @@ def finite_diff(f, axis=0, dx=1.0, method='forward', out=None, **kwargs):
 
     Parameters
     ----------
-    f : array-like
+    f : `array-like`
          An N-dimensional array.
     axis : int, optional
         The axis along which the partial derivative is evaluated.
@@ -695,7 +694,11 @@ def finite_diff(f, axis=0, dx=1.0, method='forward', out=None, **kwargs):
     method : {'central', 'forward', 'backward'}, optional
         Finite difference method which is used in the interior of the domain
          of ``f``.
-    pad_mode : {'constant', 'symmetric', 'periodic', None}, optional
+    out : `numpy.ndarray`, optional
+         An N-dimensional array to which the output is written. Has to have
+         the same shape as the input array ``f``.
+
+    pad_mode : {'constant', 'symmetric', 'periodic', ``None``}, optional
 
         'constant' : Pads values outside the domain of ``f`` with a constant
         value given by ``pad_const``.
@@ -705,24 +708,20 @@ def finite_diff(f, axis=0, dx=1.0, method='forward', out=None, **kwargs):
 
         'periodic' : Pads with the values from the other side of the array.
 
-        If None is given, one-sided forward or backward differences
-        are used at the boundary.
+        ``None`` : Use one-sided forward or backward differences at
+        the boundary.
 
     pad_const : float, optional
-        For ``pad_mode == 'constant'``, ``f`` assumes
-        ``pad_const`` for indices outside the domain of ``f``
+        For ``pad_mode == 'constant'``, ``f`` assumes ``pad_const`` for
+        indices outside the domain of ``f``
 
     edge_order : {1, 2}, optional
-        Edge-order accuracy at the boundaries if no padding is used. If
-        None the edge-order accuracy at endpoints corresponds to the
-        accuracy in the interior. Default: None
-    out : numpy.ndarray, optional
-         An N-dimensional array to which the output is written. Has to have
-         the same shape as the input array ``f``. Default: None
+        Edge-order accuracy at the boundaries if no padding is used.
+        Default: Same order as in the interior.
 
     Returns
     -------
-    out : numpy.ndarray
+    out : `numpy.ndarray`
         N-dimensional array of the same shape as ``f``. If ``out`` is
         provided, the returned object is a reference to it.
 

odl/discr/discr_mappings.py

@@ -68,7 +68,7 @@ def __init__(self, map_type, fset, partition, dspace, linear=False,
             discretized object. Its `NtuplesBase.size` must be equal
             to the total number of grid points.
         linear : bool
-            Create a linear operator if True, otherwise a non-linear
+            Create a linear operator if ``True``, otherwise a non-linear
             operator.
         order : {'C', 'F'}, optional
             Ordering of the axes in the data storage. 'C' means the
@@ -563,11 +563,11 @@ def __init__(self, fspace, partition, dspace, schemes, **kwargs):
             discretized object. Its `NtuplesBase.size` must be equal
             to the total number of grid points, and its `FnBase.field`
             must be the same as that of the function space.
-        schemes : string or sequence of string
+        schemes : string or `sequence` of strings
             Indicates which interpolation scheme to use for which axis.
             A single string is interpreted as a global scheme for all
             axes.
-        nn_variants : string or sequence of string, optional
+        nn_variants : string or `sequence` of strings, optional
             Which variant ('left' or 'right') to use in nearest neighbor
             interpolation for which axis. A single string is interpreted
             as a global variant for all axes.
@@ -709,9 +709,9 @@ class _Interpolator(object):
     def __init__(self, coord_vecs, values, input_type):
         """Initialize a new instance.
 
-        coord_vecs : sequence of numpy.ndarray
+        coord_vecs : `sequence` of `numpy.ndarray`'s
             Coordinate vectors defining the interpolation grid
-        values : array-like
+        values : `array-like`
             Grid values to use for interpolation
         input_type : {'array', 'meshgrid'}
             Type of expected input values in ``__call__``
@@ -744,15 +744,15 @@ def __call__(self, x, out=None):
 
         Parameters
         ----------
-        x : meshgrid or numpy.ndarray
+        x : `meshgrid` or `numpy.ndarray`
             Evaluation points of the interpolator
-        out : numpy.ndarray, optional
+        out : `numpy.ndarray`, optional
             Array to which the results are written. Needs to have
             correct shape according to input ``x``.
 
         Returns
         -------
-        out : numpy.ndarray
+        out : `numpy.ndarray`
             Interpolated values. If ``out`` was given, the returned
             object is a reference to it.
         """
@@ -827,9 +827,9 @@ class _NearestInterpolator(_Interpolator):
     def __init__(self, coord_vecs, values, input_type, variant):
         """Initialize a new instance.
 
-        coord_vecs : sequence of numpy.ndarray
+        coord_vecs : `sequence` of `numpy.ndarray`'s
             Coordinate vectors defining the interpolation grid
-        values : array-like
+        values : `array-like`
             Grid values to use for interpolation
         input_type : {'array', 'meshgrid'}
             Type of expected input values in ``__call__``
@@ -956,15 +956,15 @@ class _PerAxisInterpolator(_Interpolator):
     def __init__(self, coord_vecs, values, input_type, schemes, nn_variants):
         """Initialize a new instance.
 
-        coord_vecs : sequence of numpy.ndarray
+        coord_vecs : `sequence` of `numpy.ndarray`'s
             Coordinate vectors defining the interpolation grid
-        values : array-like
+        values : `array-like`
             Grid values to use for interpolation
         input_type : {'array', 'meshgrid'}
             Type of expected input values in ``__call__``
-        schemes : sequence of string
+        schemes : `sequence` of strings
             Indicates which interpolation scheme to use for which axis
-        nn_variants : sequence of string
+        nn_variants : `sequence` of strings
             Which variant ('left' or 'right') to use in nearest neighbor
             interpolation for which axis.
             This option has no effect for schemes other than nearest
@@ -1024,9 +1024,9 @@ class _LinearInterpolator(_PerAxisInterpolator):
     def __init__(self, coord_vecs, values, input_type):
         """Initialize a new instance.
 
-        coord_vecs : sequence of numpy.ndarray
+        coord_vecs : `sequence` of `numpy.ndarray`'s
             Coordinate vectors defining the interpolation grid
-        values : array-like
+        values : `array-like`
             Grid values to use for interpolation
         input_type : {'array', 'meshgrid'}
             Type of expected input values in ``__call__``

odl/discr/discr_ops.py

@@ -182,17 +182,17 @@ def __init__(self, domain, range=None, ran_shp=None, **kwargs):
             For the default ``None``, a space with the same attributes
             as ``domain`` is used, except for its shape, which is set
             to ``ran_shp``.
-        ran_shp : sequence of int, optional
+        ran_shp : `sequence` of ints, optional
             Shape of the range of this operator. This can be provided
             instead of ``range`` and is mandatory if ``range`` is
             ``None``.
-        offset : int or sequence of int, optional
+        offset : int or `sequence` of ints, optional
             Number of cells to add to/remove from the left of
             ``domain.partition``. By default, the difference is
             distributed evenly, with preference for left in case of
             ambiguity.
             This option is can only be used together with ``ran_shp``.
-        pad_mode : str, optional
+        pad_mode : string, optional
             Method to be used to fill in missing values in an enlarged array.
 
             ``'constant'``: Fill with ``pad_const``.

odl/discr/discretization.py

@@ -206,10 +206,11 @@ def __eq__(self, other):
         Returns
         -------
         equals : bool
-            True if ``other`` is a `DiscretizedSet`
+            ``True`` if ``other`` is a `DiscretizedSet`
             instance and all attributes `uspace`, `dspace`,
             `DiscretizedSet.sampling` and `DiscretizedSet.interpolation`
-            of ``other`` and this discretization are equal, False otherwise.
+            of ``other`` and this discretization are equal, ``False``
+            otherwise.
         """
         if other is self:
             return True
@@ -281,7 +282,7 @@ def asarray(self, out=None):
 
         Parameters
         ----------
-        out : numpy.ndarray, optional
+        out : `numpy.ndarray`, optional
             Array in which the result should be written in-place.
             Has to be contiguous and of the correct dtype.
         """
@@ -293,8 +294,8 @@ def __eq__(self, other):
         Returns
         -------
         equals : bool
-            True if all entries of ``other`` are equal to this
-            vector's entries, False otherwise.
+            ``True`` if all entries of ``other`` are equal to this
+            vector's entries, ``False`` otherwise.
         """
         return (other in self.space and
                 self.ntuple == other.ntuple)
@@ -304,7 +305,7 @@ def __getitem__(self, indices):
 
         Parameters
         ----------
-        indices : int or slice
+        indices : int or `slice`
             The position(s) that should be accessed
 
         Returns
@@ -319,9 +320,9 @@ def __setitem__(self, indices, values):
 
         Parameters
         ----------
-        indices : int or slice
+        indices : int or `slice`
             The position(s) that should be set
-        values : scalar, array-like or `NtuplesBaseVector`
+        values : scalar, `array-like` or `NtuplesBaseVector`
             The value(s) that are to be assigned.
 
             If ``index`` is an int, ``value`` must be single value.
@@ -488,7 +489,7 @@ def weighting(self):
 
     @property
     def is_weighted(self):
-        """Return True if the ``dspace`` is weighted."""
+        """``True`` if the ``dspace`` is weighted."""
         return getattr(self.dspace, 'is_weighted', False)
 
     def _lincomb(self, a, x1, b, x2, out):
@@ -560,10 +561,10 @@ def dspace_type(space, impl, dtype=None):
         Template space from which to infer an adequate data space. If
         it has a `LinearSpace.field` attribute, ``dtype`` must be
         consistent with it.
-    impl : `str`
+    impl : string
         Implementation backend for the data space
-    dtype : `type`, optional
-        Data type which the space is supposed to use. If None, the
+    dtype : type, optional
+        Data type which the space is supposed to use. If ``None``, the
         space type is purely determined from ``space`` and
         ``impl``. If given, it must be compatible with the
         field of ``space``.