Merge pull request #239 from stscieisenhamer/docs

Docstring and readthedocs updates

docs/Makefile

@@ -46,6 +46,7 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  livehtml   to run with sphinx-autobuild for live updating"
 
 .PHONY: clean
 clean:
@@ -214,3 +215,8 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: livehtml
+livehtml:
+	sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+

docs/source/api.rst

@@ -4,22 +4,72 @@ SpecViz API
 Analysis Functions
 ------------------
 .. automodapi:: specviz.analysis
-  :no-heading:
+   :no-heading:
 
 
 SpecViz core
 ------------
-.. automodapi:: specviz.core
-  :no-heading:
 
+Data Objects
+^^^^^^^^^^^^
+.. automodapi:: specviz.core.data
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
 
+Object Event Handling
+^^^^^^^^^^^^^^^^^^^^^
+.. automodapi:: specviz.core.comms
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
+
+Spectrum Layer Plotting
+^^^^^^^^^^^^^^^^^^^^^^^
+.. automodapi:: specviz.core.plots
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
+
+Emission/Absorption Line list utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodapi:: specviz.core.linelist
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
+
+Thread Helpers
+^^^^^^^^^^^^^^
+.. automodapi:: specviz.core.threads
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
+
+
 Interfaces
 ----------
 .. automodapi:: specviz.interfaces
-  :no-heading:
+   :no-heading:
+
+Model Factories
+^^^^^^^^^^^^^^^
+.. automodapi:: specviz.interfaces.factories
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
 
+Model Initialization
+^^^^^^^^^^^^^^^^^^^^
+.. automodapi:: specviz.interfaces.initializers
+   :no-heading:
+   :no-main-docstr:
+   :headings:""
 
+
 I/O module
 ----------
 .. automodapi:: specviz.io
-  :no-heading:
+   :no-heading:
+
+.. automodapi:: specviz.io.yaml_loader
+   :no-heading:

specviz/analysis/models/blackbody.py

@@ -10,10 +10,41 @@
 
 
 class BlackBody(Fittable1DModel):
+    """
+    Produce a blackbody flux spectrum
+
+    Notes
+    -----
+    See `~astropy.modeling.Fittable1DModel`
+    for further details on modeling and all
+    possible parameters that can be passed in.
+
+    Description of the blackbody function itself is described in
+    `~astropy.analytic_functions.blackbody`
+    """
     temp = Parameter(default=5000, min=10.)
     norm = Parameter(default=1.)
 
     def evaluate(self, x, temp, norm):
+        """
+        Evaluate the blackbody for a given temperature over a wavalength range
+
+        Parameters
+        ----------
+        x: numpy.ndarray
+            The wavelengths to evaulate over.
+
+        temp: float
+            The temperature to evualate at.
+
+        norm: float
+            The normalization factor.
+
+        Returns
+        -------
+        blackbody_flux: numpy.ndarray
+            The blackbody flux.
+        """
         # x is passed as a bare numpy array; must be
         # converted back to Quantity before calling
         # astropy's black body functions.
@@ -29,8 +60,25 @@ def evaluate(self, x, temp, norm):
 
 
 class BlackBodyInitializer(object):
+    """
+    `BlackBody` model initializer
+    """
 
     def initialize(self, instance, wave, flux):
+        """
+        Initialize the blackbody model
+
+        Parameters
+        ----------
+        instance: BlackBody
+            The `BlackBody` model
+
+        wave: numpy.ndarray
+            The wavelength range.
+
+        flux: numpy.ndarray
+            The source flux to normalize to.
+        """
         instance.wave = wave
         instance.flux = flux
 

specviz/analysis/models/spline.py

@@ -7,20 +7,66 @@
 
 
 class Spline1D(Fittable1DModel):
+    """
+    Perform a spline fit
 
+    Notes
+    -----
+    See
+    `~astropy.modeling.Fittable1DModel`
+    for further details.
+
+    The spline function is based on
+    `~scipy.interpolate.UnivariateSpline`
+    """
     degree = Parameter(default=3, fixed=True)
     smooth = Parameter(default=1, fixed=True)  # default=None crashes the app
 
     def evaluate(self, x, degree, smooth):
+        """
+        Evaluate the spline
+
+        Parameters
+        ----------
+        x: numpy.ndarray
+            The wavelengths to evaluate over.
+
+        degree: int
+            The degree of spline to evaluate.
+
+        smooth: float or None
+            The smoothing factor used to choose the number of knots.
+
+        Returns
+        -------
+        The evaluated spline
+        """
         _f = UnivariateSpline(self.wave, self.flux,
                               k=degree,
                               s=smooth)
         return _f(x)
 
 
 class Spline1DInitializer(object):
-
+    """
+    `Spline1D` model initializer
+    """
+
     def initialize(self, instance, wave, flux):
+        """
+        Initialize the `Spline1D` model.
+
+        Parameters
+        ----------
+        instance: `Spline1D` instance
+            The `Spline1D` model.
+
+        wave: numpy.ndarray
+            The wavelength range.
+
+        flux: numpy.ndarray
+            The source flux.
+        """
         instance.wave = wave
         instance.flux = flux
 

specviz/core/annotation.py

@@ -12,6 +12,7 @@
     'vertical':   {'anchor': (0, 0.5), 'angle': -90}
 }
 
+
 class LineIDMarker(TextItem):
     ''' This class handles the drawing of a modified TextItem that's
         augmented with a linear vertical marker. These items are used
@@ -62,5 +63,3 @@ def paint(self, p, *args):
         pen = QPen(QColor(functions.mkColor(self._color)))
         p.setPen(pen)
         p.drawPolygon(polygon)
-
-