doc tweaks

docs/generate.sh

 rm -rf docs/build docs/source/mod
-#sphinx-apidoc -l -e -d 2 -o docs/source/mod nifty4
-python docs/better_apidoc.py -l -e -d 3 -t docs/generation-templates -o docs/source/mod nifty4
+sphinx-apidoc -l -e -d 2 -o docs/source/mod nifty4
+#python docs/better_apidoc.py -l -e -d 3 -t docs/generation-templates -o docs/source/mod nifty4
 sphinx-build -b html docs/source/ docs/build/

docs/source/concepts/domains.rst

@@ -4,17 +4,14 @@ NIFTy's domain classes
 .. currentmodule:: nifty4
 
 
-**Abstract base class**
+Abstract base class
+-------------------
 
 :class:`Domain` is the abstract ancestor for all of NIFTy's domains.
 
-.. toctree::
-    :maxdepth: 1
 
-    Domain                          <../mod/nifty4.domains.domain>
-
-
-**Unstructured domains**
+Unstructured domains
+--------------------
 
 Domains can be either *structured* (i.e. there is geometrical information
 associated with them, like position in space and volume factors),
@@ -23,24 +20,15 @@ or *unstructured* (meaning that the data points have no associated manifold).
 Unstructured domains can be described by instances of NIFTy's
 :class:`UnstructuredDomain` class.
 
-.. toctree::
-    :maxdepth: 1
-
-    UnstructuredDomain              <../mod/nifty4.domains.unstructured_domain>
 
-
-**Structured domains**
+Structured domains
+------------------
 
 In contrast to unstructured domains, these domains have an assigned geometry.
 NIFTy requires these domains to provide the volume elements of their grid cells.
 The additional methods are described in the abstract class
 :class:`StructuredDomain`.
 
-.. toctree::
-    :maxdepth: 1
-
-    StructuredDomain                <../mod/nifty4.domains.structured_domain>
-
 NIFTy comes with several concrete subclasses of :class:`StructuredDomain`.
 
 :class:`RGSpace` represents a regular Cartesian grid with an arbitrary
@@ -52,13 +40,3 @@ This domain can be constructed to represent either position or harmonic space.
 contains spherical harmonic coefficients.
 
 :class:`PowerSpace` is used to describe one-dimensional power spectra.
-
-.. toctree::
-    :maxdepth: 1
-
-    RGSpace                         <../mod/nifty4.domains.rg_space>
-    HPSpace                         <../mod/nifty4.domains.hp_space>
-    GLSpace                         <../mod/nifty4.domains.gl_space>
-    LMSpace                         <../mod/nifty4.domains.lm_space>
-
-    PowerSpace                      <../mod/nifty4.domains.power_space>

docs/source/index.rst

@@ -23,8 +23,8 @@ Contents
 
    ift
    Gallery <http://wwwmpa.mpa-garching.mpg.de/ift/nifty/gallery/>
-   start
    installation
+   start
    code
 
 Indices and tables

nifty4/domains/domain.py

@@ -52,12 +52,12 @@ class Domain(with_metaclass(
 
         Parameters
         ----------
-        x: Domain
+        x : Domain
             The domain `self` is compared to.
 
         Returns
         -------
-        bool: True iff `self` and x describe the same domain.
+        bool : True iff `self` and x describe the same domain.
         """
         if self is x:  # shortcut for simple case
             return True
@@ -74,22 +74,17 @@ class Domain(with_metaclass(
 
     @abc.abstractproperty
     def shape(self):
-        """The shape of the array-like object required to store information
-        living on the domain.
+        """tuple of ints: number of pixels along each axis
 
-        Returns
-        -------
-        tuple of ints: shape of the required array-like object
+        The shape of the array-like object required to store information
+        living on the domain.
         """
         raise NotImplementedError
 
     @abc.abstractproperty
     def size(self):
-        """Number of data elements associated with this domain.
-        Equivalent to the products over all entries in the domain's shape.
+        """int: total number of pixels.
 
-        Returns
-        -------
-        int: number of data elements
+        Equivalent to the products over all entries in the domain's shape.
         """
         raise NotImplementedError

nifty4/domains/gl_space.py

@@ -83,14 +83,12 @@ class GLSpace(StructuredDomain):
 
     @property
     def nlat(self):
-        """ Number of latitudinal bins (or rings) that are used for this
-        pixelization.
-        """
+        """int : number of rings in this domain"""
         return self._nlat
 
     @property
     def nlon(self):
-        """Number of longitudinal bins that are used for this pixelization."""
+        """int : pixels per ring in this domain"""
         return self._nlon
 
     def get_default_codomain(self):
@@ -101,7 +99,7 @@ class GLSpace(StructuredDomain):
         Returns
         -------
         LMSpace
-            The parter domain
+            The partner domain
         """
         from .. import LMSpace
         return LMSpace(lmax=self._nlat-1, mmax=self._nlon//2)

nifty4/domains/hp_space.py

@@ -61,7 +61,7 @@ class HPSpace(StructuredDomain):
 
     @property
     def nside(self):
-        """Returns the nside of the corresponding HEALPix pixelization."""
+        """int : HEALPix Nside parameter of this domain"""
         return self._nside
 
     def get_default_codomain(self):
@@ -71,7 +71,7 @@ class HPSpace(StructuredDomain):
         Returns
         -------
         LMSpace
-            The parter domain
+            The partner domain
 
         Notes
         -----

nifty4/domains/lm_space.py

@@ -110,15 +110,19 @@ class LMSpace(StructuredDomain):
 
     @property
     def lmax(self):
-        """ Returns the maximum :math:`l` value of any spherical harmonic
-        coefficient :math:`a_{lm}` that is represented in this Space.
+        """int : maximum allowed :math:`l`
+
+        The maximum :math:`l` value of any spherical harmonic
+        coefficient :math:`a_{lm}` that is represented in this domain.
         """
         return self._lmax
 
     @property
     def mmax(self):
-        """ Returns the maximum :math:`m` value of any spherical harmonic
-        coefficient :math:`a_{lm}` that is represented in this Space.
+        """int : maximum allowed :math:`m`
+
+        The maximum :math:`m` value of any spherical harmonic
+        coefficient :math:`a_{lm}` that is represented in this domain.
         """
         return self._mmax
 
@@ -130,7 +134,7 @@ class LMSpace(StructuredDomain):
         Returns
         -------
         GLSpace
-            The parter domain
+            The partner domain
         """
         from .. import GLSpace
         return GLSpace(self.lmax+1, self.mmax*2+1)

nifty4/domains/power_space.py

@@ -30,19 +30,19 @@ class PowerSpace(StructuredDomain):
     Parameters
     ----------
     harmonic_partner : StructuredDomain
-        The harmonic dmain of which this is the power space.
-    binbounds : None, or tuple of float
+        The harmonic domain of which this is the power space.
+    binbounds : None, or tuple of float (default: None)
         if None:
             There will be as many bins as there are distinct k-vector lengths
             in the harmonic partner space.
-            The "binbounds" property of the PowerSpace will also be None.
+            The `binbounds` property of the PowerSpace will also be None.
         else:
             the bin bounds requested for this PowerSpace. The array
             must be sorted and strictly ascending. The first entry is the right
             boundary of the first bin, and the last entry is the left boundary
-            of the last bin, i.e. thee will be len(binbounds)+1 bins in total,
-            with the first and last bins reaching to -+infinity, respectively.
-            (default : None)
+            of the last bin, i.e. thee will be `len(binbounds)+1` bins in
+            total, with the first and last bins reaching to -+infinity,
+            respectively.
     """
 
     _powerIndexCache = {}
@@ -191,6 +191,7 @@ class PowerSpace(StructuredDomain):
 
     @property
     def harmonic(self):
+        """bool : Always False for this class."""
         return False
 
     @property
@@ -209,12 +210,15 @@ class PowerSpace(StructuredDomain):
 
     @property
     def harmonic_partner(self):
-        """Returns the Space of which this is the power space."""
+        """StructuredDomain : the harmonic domain associated with `self`."""
         return self._harmonic_partner
 
     @property
     def binbounds(self):
-        """Returns the boundaries between the power spectrum bins as a tuple.
+        """None or tuple of float : inner bin boundaries
+
+        The boundaries between bins, starting with the right boundary of the
+        first bin, up to the left boundary of the last bin.
 
         `None` is used to indicate natural binning.
         """
@@ -222,12 +226,13 @@ class PowerSpace(StructuredDomain):
 
     @property
     def pindex(self):
-        """Returns a data object having the shape of the harmonic partner
-        space containing the indices of the power bin a pixel belongs to.
+        """data_object : bin indices
+
+        Bin index for every pixel in the harmonic partner.
         """
         return self._pindex
 
     @property
     def k_lengths(self):
-        """Returns a sorted array of all k-modes."""
+        """numpy.ndarray(float) : sorted array of all k-vector lengths."""
         return self._k_lengths

nifty4/domains/structured_domain.py

@@ -67,7 +67,7 @@ class StructuredDomain(Domain):
 
     @abc.abstractproperty
     def harmonic(self):
-        """ Returns True iff this domain is a harmonic domain."""
+        """bool : True iff this domain is a harmonic domain."""
         raise NotImplementedError
 
     def get_k_length_array(self):

nifty4/operators/endomorphic_operator.py

@@ -29,8 +29,8 @@ class EndomorphicOperator(LinearOperator):
 
     @property
     def target(self):
-        """
-        DomainTuple
-            Returns `self.domain`, because this is also the target domain
-            for endomorphic operators."""
+        """DomainTuple : returns :attr:`domain`
+
+        Returns `self.domain`, because this is also the target domain
+        for endomorphic operators."""
         return self.domain

nifty4/operators/linear_operator.py

@@ -56,41 +56,33 @@ class LinearOperator(with_metaclass(
 
     @abc.abstractproperty
     def domain(self):
-        """
-        DomainTuple
-            The domain on which the Operator's input Field lives.
-            Every Operator which inherits from the abstract LinearOperator
-            base class must have this attribute.
-        """
+        """DomainTuple : the operator's input domain
+
+            The domain on which the Operator's input Field lives."""
         raise NotImplementedError
 
     @abc.abstractproperty
     def target(self):
-        """
-        DomainTuple
-            The domain on which the Operator's output Field lives.
-            Every Operator which inherits from the abstract LinearOperator
-            base class must have this attribute.
-        """
+        """DomainTuple : the operator's output domain
+
+            The domain on which the Operator's output Field lives."""
         raise NotImplementedError
 
     @property
     def inverse(self):
-        """
-        LinearOperator
-            Returns a LinearOperator object which behaves as if it were
-            the inverse of this operator.
-        """
+        """LinearOperator : the inverse of `self`
+
+        Returns a LinearOperator object which behaves as if it were
+        the inverse of this operator."""
         from .inverse_operator import InverseOperator
         return InverseOperator(self)
 
     @property
     def adjoint(self):
-        """
-        LinearOperator
-            Returns a LinearOperator object which behaves as if it were
-            the adjoint of this operator.
-        """
+        """LinearOperator : the adjoint of `self`
+
+        Returns a LinearOperator object which behaves as if it were
+        the adjoint of this operator."""
         from .adjoint_operator import AdjointOperator
         return AdjointOperator(self)
 
@@ -137,20 +129,17 @@ class LinearOperator(with_metaclass(
 
     @abc.abstractproperty
     def capability(self):
-        """ Specifies the application modes supported by this operator
+        """int : the supported operation modes
 
-        Returns
-        -------
-        int
-            This is any subset of LinearOperator.{TIMES, ADJOINT_TIMES,
-            INVERSE_TIMES, ADJOINT_INVERSE_TIMES, INVERSE_ADJOINT_TIMES},
-            joined together by the "|" operator.
+        Returns the suppoerted subset of :attr:`TIMES`, :attr:`ADJOINT_TIMES`,
+        :attr:`INVERSE_TIMES`, and :attr:`ADJOINT_INVERSE_TIMES`,
+        joined together by the "|" operator.
         """
         raise NotImplementedError
 
     @abc.abstractmethod
     def apply(self, x, mode):
-        """ Applies the Operator to a given Field, in a specified mode.
+        """ Applies the Operator to a given `x`, in a specified `mode`.
 
         Parameters
         ----------
@@ -175,7 +164,7 @@ class LinearOperator(with_metaclass(
         raise NotImplementedError
 
     def __call__(self, x):
-        """Same as times()"""
+        """Same as :meth:`times`"""
         return self.apply(x, self.TIMES)
 
     def times(self, x):
@@ -244,7 +233,7 @@ class LinearOperator(with_metaclass(
         return self.apply(x, self.ADJOINT_INVERSE_TIMES)
 
     def inverse_adjoint_times(self, x):
-        """Same as adjoint_inverse_times()"""
+        """Same as :meth:`adjoint_inverse_times`"""
         return self.apply(x, self.ADJOINT_INVERSE_TIMES)
 
     def _check_mode(self, mode):
@@ -262,7 +251,9 @@ class LinearOperator(with_metaclass(
             raise ValueError("The operator's and field's domains don't match.")
 
     def draw_sample(self):
-        """ Generates a sample from a Gaussian distribution with zero mean and
+        """Generate a zero-mean sample
+
+        Generates a sample from a Gaussian distribution with zero mean and
         covariance given by the operator.
 
         Returns