Merge pull request #107 from jlaehne/docstrings

Fix inconsistent docstring formatting

lumispy/signals/cl_spectrum.py

@@ -16,7 +16,9 @@
 # You should have received a copy of the GNU General Public License
 # along with LumiSpy.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Signal class for Cathodoluminescence spectral data.
+"""
+Signal class for cathodoluminescence spectral data
+--------------------------------------------------
 """
 
 from inspect import getfullargspec
@@ -30,7 +32,7 @@
 
 
 class CLSpectrum(LumiSpectrum):
-    """General 1D Cathodoluminescence signal class."""
+    """**General 1D cathodoluminescence signal class.**"""
 
     _signal_type = "CL"
     _signal_dimension = 1
@@ -122,10 +124,12 @@ def remove_spikes(
         else:
             return signal
 
-    REMOVE_SPIKES_DOCSTRINGS = """
-        Hyperspy-based spike removal tool adapted to Lumispy to run non-interactively and
-        without noise addition by default.
+    REMOVE_SPIKES_DOCSTRINGS = """HyperSpy-based spike removal tool adapted to
+        LumiSpy to run non-interactively and without noise addition by default.
         %s
+        
+        Other Parameters
+        ----------------
         show_diagnosis_histogram: bool
             Plot or not the derivative histogram to show the magnitude of the spikes present.
         inplace: bool
@@ -147,6 +151,8 @@ def remove_spikes(
 
 
 class LazyCLSpectrum(LazySignal, CLSpectrum):
+    """**General lazy 1D cathodoluminescence signal class.**"""
+
     _lazy = True
 
     pass
@@ -157,6 +163,8 @@ class LazyCLSpectrum(LazySignal, CLSpectrum):
 
 
 class CLSEMSpectrum(CLSpectrum):
+    """**1D scanning electron microscopy cathodoluminescence signal class.**"""
+
     _signal_type = "CL_SEM"
 
     def correct_grating_shift(
@@ -207,6 +215,8 @@ def correct_grating_shift(
 
 
 class LazyCLSEMSpectrum(LazySignal, CLSEMSpectrum):
+    """**Lazy 1D scanning electron microscopy cathodoluminescence signal class.**"""
+
     _lazy = True
 
     pass
@@ -217,13 +227,15 @@ class LazyCLSEMSpectrum(LazySignal, CLSEMSpectrum):
 
 
 class CLSTEMSpectrum(CLSpectrum):
+    """**1D scanning transmission electron microscopy cathodoluminescence signal class.**"""
 
     _signal_type = "CL_STEM"
 
     pass
 
 
 class LazyCLSTEMSpectrum(LazySignal, CLSTEMSpectrum):
+    """**Lazy 1D scanning transmission electron microscopy cathodoluminescence signal class.**"""
 
     _lazy = True
 

lumispy/signals/cl_transient.py

@@ -16,7 +16,9 @@
 # You should have received a copy of the GNU General Public License
 # along with LumiSpy.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Signal class for Luminescence transient data (2D).
+"""
+Signal class for cathodoluminescence transient data (2D)
+--------------------------------------------------------
 """
 
 from hyperspy.signals import Signal2D
@@ -26,7 +28,7 @@
 
 
 class CLTransient(LumiTransient):
-    """CL 2D luminescence signal class (transient/time resolved)."""
+    """**General 2D cathodoluminescence signal class (transient/time resolved)**"""
 
     _signal_type = "TRCL"
     _signal_dimension = 2
@@ -35,6 +37,8 @@ class CLTransient(LumiTransient):
 
 
 class LazyCLTransient(LazySignal, CLTransient):
+    """**General lazy 2D cathodoluminescence signal class (transient/time resolved)**"""
+
     _lazy = True
 
     pass

lumispy/signals/common_luminescence.py

@@ -16,15 +16,17 @@
 # You should have received a copy of the GNU General Public License
 # along with LumiSpy.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Signal class for Luminescence data (BaseSignal class).
+"""
+Signal class for luminescence data (BaseSignal class)
+-----------------------------------------------------
 """
 
 from numpy import isnan
 from warnings import warn
 
 
 class CommonLumi:
-    """General Luminescence signal class (dimensionless)."""
+    """**General luminescence signal class (dimensionless)**"""
 
     def crop_edges(self, crop_px):
         """Crop the amount of pixels from the four edges of the scanning
@@ -156,7 +158,7 @@ def normalize(self, pos=float("nan"), element_wise=False, inplace=False):
         pos : float, int
             If 'nan' (default), spectra are normalized to the maximum.
             If `float`, position along signal axis in calibrated units at which
-                to normalize the spectra.
+            to normalize the spectra.
             If `int`, index along signal axis at which to normalize the spectra.
         element_wise: boolean
             If `False` (default), a spectrum image is normalized by a common factor.

lumispy/signals/el_spectrum.py

@@ -16,7 +16,9 @@
 # You should have received a copy of the GNU General Public License
 # along with LumiSpy.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Signal class for Electroluminescence spectral data.
+"""
+Signal class for electroluminescence spectral data
+--------------------------------------------------
 """
 
 from hyperspy._signals.lazy import LazySignal
@@ -25,9 +27,7 @@
 
 
 class ELSpectrum(LumiSpectrum):
-    """General 1D Electroluminescence signal class.
-    ----------
-    """
+    """**General 1D electroluminescence signal class**"""
 
     _signal_type = "EL"
     _signal_dimension = 1
@@ -36,6 +36,8 @@ class ELSpectrum(LumiSpectrum):
 
 
 class LazyELSpectrum(LazySignal, ELSpectrum):
+    """**General lazy 1D electroluminescence signal class**"""
+
     _lazy = True
 
     pass

lumispy/signals/luminescence_spectrum.py

@@ -19,9 +19,10 @@
 """Signal class for Luminescence spectral data (1D).
 """
 import warnings
+import numpy as np
 from inspect import getfullargspec
 from warnings import warn
-import numpy as np
+from textwrap import indent
 
 
 from hyperspy.signals import Signal1D
@@ -49,7 +50,7 @@
 
 
 class LumiSpectrum(Signal1D, CommonLumi):
-    """General 1D Luminescence signal class."""
+    """**General 1D luminescence signal class.**"""
 
     _signal_type = "Luminescence"
     _signal_dimension = 1
@@ -128,8 +129,8 @@ def to_eV(self, inplace=True, jacobian=True):
         >>> S1 = LumiSpectrum(np.ones(20), DataAxis(axis = np.arange(200,400,10)), ))
         >>> S1.to_eV()
 
-        Note
-        ----
+        Notes
+        -----
         Using a non-linear axis works only for the RELEASE_next_minor development
         branch of HyperSpy.
         """
@@ -260,46 +261,45 @@ def to_eV(self, inplace=True, jacobian=True):
             return s2
 
     TO_INVCM_DOCSTRING = """
-    The intensity is converted from counts/nm (counts/µm) to counts/cm^-1
-    by doing a Jacobian transformation, see e.g. Wang and Townsend,
-    J. Lumin. 142, 202 (2013), doi:10.1016/j.jlumin.2013.03.052, which
-    ensures that integrated signals are correct also in the wavenumber 
-    domain. If the variance of the signal is known, i.e.
-    `metadata.Signal.Noise_properties.variance` is a signal representing the
-    variance, a squared renormalization of the variance is performed.
-    Note that if the variance is a number (not a signal instance), it is
-    converted to a signal if the Jacobian transformation is performed
-
-    Parameters
-    ----------
-    inplace : boolean
-        If `False`, a new signal object is created and returned. Otherwise
-        (default) the operation is performed on the existing signal object.
-    jacobian : boolean
-        The default is to do the Jacobian transformation (recommended at
-        least for luminescence signals), but the transformation can be
-        suppressed by setting this option to `False`.
-    """
+        The intensity is converted from counts/nm (counts/µm) to counts/cm^-1
+        by doing a Jacobian transformation, see e.g. Wang and Townsend,
+        J. Lumin. 142, 202 (2013), doi:10.1016/j.jlumin.2013.03.052, which
+        ensures that integrated signals are correct also in the wavenumber 
+        domain. If the variance of the signal is known, i.e.
+        `metadata.Signal.Noise_properties.variance` is a signal representing the
+        variance, a squared renormalization of the variance is performed.
+        Note that if the variance is a number (not a signal instance), it is
+        converted to a signal if the Jacobian transformation is performed
+
+        Parameters
+        ----------
+        inplace : boolean
+            If `False`, a new signal object is created and returned. Otherwise
+            (default) the operation is performed on the existing signal object.
+        jacobian : boolean
+            The default is to do the Jacobian transformation (recommended at
+            least for luminescence signals), but the transformation can be
+            suppressed by setting this option to `False`.
+        """
 
     TO_INVCM_EXAMPLE = """
-    Examples
-    --------
-    >>> import numpy as np
-    >>> from lumispy import LumiSpectrum
-    >>> S1 = LumiSpectrum(np.ones(20), DataAxis(axis = np.arange(200,400,10)), ))
-    >>> S1.to_invcm()
-
-    Note
-    ----
-    Using a non-linear axis works only for the RELEASE_next_minor development
-    branch of HyperSpy.    
-    """
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from lumispy import LumiSpectrum
+        >>> S1 = LumiSpectrum(np.ones(20), DataAxis(axis = np.arange(200,400,10)), ))
+        >>> S1.to_invcm()
+
+        Notes
+        -----
+        Using a non-linear axis works only for the RELEASE_next_minor development
+        branch of HyperSpy.    
+        """
 
     def to_invcm(self, inplace=True, jacobian=True):
         """Converts signal axis of 1D signal to non-linear wavenumber axis
         (cm^-1). Assumes wavelength in units of nm unless the axis units are
         specifically set to µm.
-
         %s
         %s
         """
@@ -426,17 +426,17 @@ def to_invcm(self, inplace=True, jacobian=True):
     to_invcm.__doc__ %= (TO_INVCM_DOCSTRING, TO_INVCM_EXAMPLE)
 
     TO_INVCMREL_EXAMPLE = """
-    Examples
-    --------
-    >>> import numpy as np
-    >>> from lumispy import LumiSpectrum
-    >>> S1 = LumiSpectrum(np.ones(20), DataAxis(axis = np.arange(200,400,10)), ))
-    >>> S1.to_invcm(laser=325)
-
-    Note
-    ----
-    Using a non-linear axis works only for the RELEASE_next_minor development
-    branch of HyperSpy.    
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from lumispy import LumiSpectrum
+        >>> S1 = LumiSpectrum(np.ones(20), DataAxis(axis = np.arange(200,400,10)), ))
+        >>> S1.to_invcm(laser=325)
+
+        Notes
+        -----
+        Using a non-linear axis works only for the RELEASE_next_minor development
+        branch of HyperSpy.    
     """
 
     def to_invcm_relative(self, laser, inplace=True, jacobian=True):
@@ -504,10 +504,11 @@ def remove_background_from_file(self, background=None, inplace=False, **kwargs):
         Parameters
         ----------
         background : array shape (2, n) or Signal1D
-            An array containing the background x-axis and the intensity values [[xs],[ys]] or a Signal1D object.
-            If the x-axis values do not match the signal_axes, then interpolation is done before subtraction.
-            If only the intensity values are provided, [ys], the functions assumes no interpolation needed.
-
+            An array containing the background x-axis and the intensity values
+            [[xs],[ys]] or a Signal1D object. If the x-axis values do not match
+            the signal_axes, then interpolation is done before subtraction. If
+            only the intensity values are provided, [ys], the functions assumes
+            no interpolation needed.
         inplace : boolean
             If False, it returns a new object with the transformation. If True,
             the original object is transformed, returning no object.
@@ -517,8 +518,8 @@ def remove_background_from_file(self, background=None, inplace=False, **kwargs):
         signal : LumiSpectrum
             A background subtracted signal.
 
-        Note
-        ----
+        Notes
+        -----
         This function does not work with non-linear axes.
         """
         if hasattr(self.metadata.Signal, "background_subtracted"):
@@ -619,8 +620,8 @@ def savetxt(
     savetxt.__doc__ %= (SAVETXT_DOCSTRING, SAVETXT_PARAMETERS, SAVETXT_EXAMPLE)
 
     TOARRAY_EXAMPLE = """
-    Note
-    ----
+    Notes
+    -----
     The output of this function can be used to convert a signal object to a
     pandas dataframe, e.g. using `df = pd.Dataframe(S.to_array())`.
 
@@ -652,8 +653,8 @@ def savetxt(
     def to_array(self, axes=True, transpose=False):
         """Returns luminescence spectrum object as numpy array (optionally
         including the axes).
-        %s
-        %s
+            %s
+            %s
         %s
         """
         return to_array(self, axes, transpose)
@@ -674,12 +675,12 @@ def px_to_nm_grating_solver(
         the grating equation. See `lumispy.axes.solve_grating_equation` for
         more details.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         %s
-        inplace : bool
-            If False, it returns a new object with the transformation. If True,
-            the original object is transformed, returning no object.
+            inplace : bool
+                If False, it returns a new object with the transformation. If
+                True, the original object is transformed, returning no object.
 
         Returns
         -------
@@ -714,10 +715,14 @@ def px_to_nm_grating_solver(
 
         return s
 
-    px_to_nm_grating_solver.__doc__ %= GRATING_EQUATION_DOCSTRING_PARAMETERS
+    px_to_nm_grating_solver.__doc__ %= GRATING_EQUATION_DOCSTRING_PARAMETERS.replace(
+        "\n", "\n\t"
+    )
 
 
 class LazyLumiSpectrum(LazySignal, LumiSpectrum):
+    """**General lazy 1D luminescence signal class.**"""
+
     _lazy = True
 
     pass