update docstrings

Author: dustinvtran

edward/inferences/inference.py

@@ -13,7 +13,19 @@
 
 @six.add_metaclass(abc.ABCMeta)
 class Inference(object):
-  """Base class for Edward inference methods.
+  """Abstract base class for inference. All inference algorithms in
+  Edward inherit from ``Inference``, sharing common methods and
+  properties via a class hierarchy.
+
+  Specific algorithms typically inherit from other subclasses of
+  ``Inference`` rather than ``Inference`` directly. For example, one
+  might inherit from the abstract classes ``MonteCarlo`` or
+  ``VariationalInference``.
+
+  To build an algorithm inheriting from ``Inference``, one must at the
+  minimum implement ``initialize`` and ``update``: the former builds
+  the computational graph for the algorithm; the latter runs the
+  computational graph for the algorithm.
   """
   def __init__(self, latent_vars=None, data=None):
     """Initialization.

edward/inferences/monte_carlo.py

@@ -14,7 +14,12 @@
 
 @six.add_metaclass(abc.ABCMeta)
 class MonteCarlo(Inference):
-  """Base class for Monte Carlo inference methods.
+  """Abstract base class for Monte Carlo. Specific Monte Carlo methods
+  inherit from ``MonteCarlo``, sharing methods in this class.
+
+  To build an algorithm inheriting from ``MonteCarlo``, one must at the
+  minimum implement ``build_update``: it determines how to assign
+  the samples in the ``Empirical`` approximations.
   """
   def __init__(self, latent_vars=None, data=None):
     """Initialization.
@@ -143,7 +148,7 @@ def print_progress(self, info_dict):
   @abc.abstractmethod
   def build_update(self):
     """Build update rules, returning an assign op for parameters in
-    the Empirical random variables.
+    the ``Empirical`` random variables.
 
     Any derived class of ``MonteCarlo`` **must** implement this method.
 

edward/inferences/variational_inference.py

@@ -19,7 +19,14 @@
 
 @six.add_metaclass(abc.ABCMeta)
 class VariationalInference(Inference):
-  """Base class for variational inference methods.
+  """Abstract base class for variational inference. Specific
+  variational inference methods inherit from ``VariationalInference``,
+  sharing methods such as a default optimizer.
+
+  To build an algorithm inheriting from ``VariaitonalInference``, one
+  must at the minimum implement ``build_loss_and_gradients``: it
+  determines the loss function and gradients to apply for a given
+  optimizer.
   """
   def __init__(self, *args, **kwargs):
     super(VariationalInference, self).__init__(*args, **kwargs)