Merge pull request #32 from aimalz/issue/27/sphinx

Various API docs improvements, closes #32.

.travis.yml

@@ -23,8 +23,8 @@ script:
   # Run the demo notebook, to make demo.html:
   - jupyter nbconvert --ExecutePreprocessor.kernel_name=python --ExecutePreprocessor.timeout=600 --to html --execute docs/notebooks/demo.ipynb ; cp docs/notebooks/demo.html .
   - jupyter nbconvert --ExecutePreprocessor.kernel_name=python --ExecutePreprocessor.timeout=600 --to html --execute docs/notebooks/kld.ipynb ; cp docs/notebooks/kld.html .
-  # Build the docs:
-  - sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
+  # Build the docs, the same way readthedocs does it:
+  - cd docs ; sphinx-build -b html . _build/html ; cd -
 
 # Finally, if it's the master branch being updated, force-push the
 # notebook html pages to an otherwise empty "html" branch:

docs/conf.py

@@ -1,6 +1,5 @@
 import sys
 import os
-import sphinx_rtd_theme
 
 # Provide path to the python modules we want to run autodoc on
 sys.path.insert(0, os.path.abspath('../qp'))
@@ -15,8 +14,17 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode']
 
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:
+    # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so
+# no need to specify it.
 
 master_doc = 'index'
 autosummary_generate = True

docs/index.rst

@@ -32,13 +32,14 @@ these approximations.
 The PDF Class
 -------------
 
-.. autoclass:: pdf.PDF
+.. automodule:: pdf
     :members:
-
-    .. automethod:: pdf.PDF.__init__
+    :undoc-members:
 
 
 Quantification Utilities
 ------------------------
 
 .. automodule:: utils
+    :members:
+    :undoc-members:

qp/pdf.py

@@ -4,29 +4,31 @@
 
 import qp
 
-class PDF(object):
-
-    def __init__(self, truth=None, quantiles=None):
-        """
-        Initializes the PDF object with some representation of a distribution.
 
-        Parameters
-        ----------
-        truth: scipy.stats.rv_continuous object, optional
-            Continuous, parametric form of the PDF
-        quantiles: ndarray, optional
-            Array of quantile values separated by
-        """
+class PDF(object):
+    """
+    A PDF object, with some representation of a distribution.
+
+    Parameters
+    ----------
+    truth: scipy.stats.rv_continuous object, optional
+        continuous, parametric form of the PDF
+    quantiles: ndarray, optional
+        array of quantile values separated by
+    vb: boolean
+        report on progress to stdout?
+    """
+    def __init__(self, truth=None, quantiles=None, vb=True):
         self.truth = truth
         self.quantiles = quantiles
         # Should make this a proper exception rather than just printing an advisory notice
-        if self.truth is None and self.quantiles is None:
-            print('It is unwise to initialize a PDF object without inputs!')
-            return
+        if vb and self.truth is None and self.quantiles is None:
+            print 'Warning: initializing a PDF object without inputs'
         self.difs = None
         self.mids = None
         self.quantvals = None
         self.interpolator = None
+        return
 
     def evaluate(self, loc, vb=True):
         """
@@ -35,14 +37,14 @@ def evaluate(self, loc, vb=True):
         Parameters
         ----------
         loc: float or ndarray
-            Location(s) at which to evaluate the pdf
+            location(s) at which to evaluate the pdf
         vb: boolean
-            Report on progress to stdout?
+            report on progress to stdout?
 
         Returns
         -------
         val: float or ndarray
-            Value of the truth function at given location(s)
+            the value of the PDF (ot its approximation) at the requested location(s)
 
         Notes
         -----
@@ -60,26 +62,42 @@ def evaluate(self, loc, vb=True):
         return(val)
 
     def integrate(self, limits):
+        """
+        Computes the integral under the PDF between the given limits.
 
-        return
+        Parameters
+        ----------
+        limits: float, tuple
+            limits of integration
+
+        Returns
+        -------
+        integral: float
+            value of the integral
+
+        Notes
+        -----
+        This method is not yet operational, and returns `None`.
+        """
+        return None
 
     def quantize(self, percent=1., number=None, vb=True):
         """
         Computes an array of evenly-spaced quantiles.
 
         Parameters
         ----------
-        percent : float
-            The separation of the requested quantiles, in percent
-        num_points : int
-            The number of quantiles to compute.
+        percent: float
+            the separation of the requested quantiles, in percent
+        num_points: int
+            the number of quantiles to compute.
         vb: boolean
-            Report on progress to stdout?
+            report on progress to stdout?
 
         Returns
         -------
-        self.quantiles : ndarray, float
-            The quantile points.
+        self.quantiles: ndarray, float
+            the quantile points.
 
         Notes
         -----
@@ -116,7 +134,7 @@ def interpolate(self, vb=True):
         Parameters
         ----------
         vb: boolean
-            Report on progress to stdout?
+            report on progress to stdout?
 
         Returns
         -------
@@ -146,24 +164,25 @@ def approximate(self, points, vb=True):
         Parameters
         ----------
         number: int
-            The number of points over which to interpolate, bounded by the quantile value endpoints
+            the number of points over which to interpolate, bounded by the quantile value endpoints
         points: ndarray
-            The value(s) at which to evaluate the interpolated function
+            the value(s) at which to evaluate the interpolated function
         vb: boolean
-            Report on progress to stdout?
+            report on progress to stdout?
 
         Returns
         -------
         points: ndarray, float
-            The input grid upon which to interpolate
-        interpolated : ndarray, float
-            The interpolated points.
+            the input grid upon which to interpolate
+        interpolated: ndarray, float
+            the interpolated points.
 
         Notes
         -----
         Extrapolation is linear while values are positive; otherwise, extrapolation returns 0.
 
-        Example:
+        Example::
+
             x, y = p.approximate(np.linspace(-1., 1., 100))
         """
 
@@ -177,14 +196,14 @@ def approximate(self, points, vb=True):
 
     def plot(self, limits, points=None):
         """
-        Plot the PDF, in various ways.
+        Plots the PDF, in various ways.
 
         Parameters
         ----------
-        limits : tuple, float
-            Range over which to plot the PDF
+        limits: tuple, float
+            range over which to plot the PDF
         points: ndarray
-            The value(s) at which to evaluate the interpolator
+            the value(s) at which to evaluate the interpolator
 
         Notes
         -----
@@ -218,18 +237,19 @@ def kld(self, limits=(0., 1.), dx=0.01):
         Parameters
         ----------
         limits: tuple of floats
-            Endpoints of integration interval in which to calculate KLD
+            endpoints of integration interval in which to calculate KLD
         dx: float
             resolution of integration grid
 
         Returns
         -------
         KL: float
-            Value of Kullback-Leibler divergence from approximation to truth if truth is available; otherwise nothing.
+            value of Kullback-Leibler divergence from approximation to truth if truth is available; otherwise nothing.
 
         Notes
         -----
-        Example:
+        Example::
+
             d = p.kld(limits=(-1., 1.), dx=1./100))
         """
 
@@ -247,18 +267,19 @@ def rms(self, limits=(0., 1.), dx=0.01):
         Parameters
         ----------
         limits: tuple of floats
-            Endpoints of integration interval in which to calculate KLD
+            endpoints of integration interval in which to calculate KLD
         dx: float
             resolution of integration grid
 
         Returns
         -------
         RMS: float
-            Value of root mean square difference between approximation of truth if truth is available; otherwise nothing.
+            value of root mean square difference between approximation of truth if truth is available; otherwise nothing.
 
         Notes
         -----
-        Example:
+        Example::
+
             d = p.rms(limits=(-1., 1.), dx=1./100))
         """