Include pymc.model in documentation (#2885)

* Add API docs for the model module to sphinx docs

* Fix docstring, so that code is properly rendered

* Fix markup in docstrings in pymc3.model

* Unpacking operators are not part of the name, and sphinx assumes
  they are markup.

* Small changes, such as replacing markdown-style
  single backticks for marking up identifiers with proper RST style
  double backticks

* Constructor should be documented in the class docstring

* Remove defaults from docstring and use RST instead of markdown

* Reformatting of the code-example's comments

* Create a sphinx _static dir that is tracked by git

Avoids warning of sphinx that the directory does
not exist

Author: HolgerPeters

docs/source/_static/.gitignore

@@ -18,3 +18,4 @@ API Reference
    api/backends
    api/math
    api/data
+   api/model

docs/source/api.rst

@@ -0,0 +1,7 @@
+Model
+-----
+
+.. currentmodule:: pymc3.model
+.. automodule:: pymc3.model
+   :members:
+

docs/source/api/model.rst

@@ -491,81 +491,89 @@ class Model(six.with_metaclass(InitContextMeta, Context, Factor, WithMemoization
     """Encapsulates the variables and likelihood factors of a model.
 
     Model class can be used for creating class based models. To create
-    a class based model you should inherit from `Model` and
-    override `__init__` with arbitrary definitions
-    (do not forget to call base class `__init__` first).
+    a class based model you should inherit from :class:`~.Model` and
+    override :meth:`~.__init__` with arbitrary definitions (do not
+    forget to call base class :meth:`__init__` first).
 
     Parameters
     ----------
-    name : str, default '' - name that will be used as prefix for
-        names of all random variables defined within model
-    model : Model, default None - instance of Model that is
-        supposed to be a parent for the new instance. If None,
-        context will be used. All variables defined within instance
-        will be passed to the parent instance. So that 'nested' model
-        contributes to the variables and likelihood factors of
-        parent model.
-    theano_config : dict, default=None
+    name : str
+        name that will be used as prefix for names of all random
+        variables defined within model
+    model : Model
+        instance of Model that is supposed to be a parent for the new
+        instance. If ``None``, context will be used. All variables
+        defined within instance will be passed to the parent instance.
+        So that 'nested' model contributes to the variables and
+        likelihood factors of parent model.
+    theano_config : dict
         A dictionary of theano config values that should be set
         temporarily in the model context. See the documentation
-        of theano for a complete list. Set `compute_test_value` to
-        `raise` if it is None.
+        of theano for a complete list. Set config key
+        ``compute_test_value`` to `raise` if it is None.
 
     Examples
     --------
-    # How to define a custom model
-    class CustomModel(Model):
-        # 1) override init
-        def __init__(self, mean=0, sd=1, name='', model=None):
-            # 2) call super's init first, passing model and name to it
-            # name will be prefix for all variables here
-            # if no name specified for model there will be no prefix
-            super(CustomModel, self).__init__(name, model)
-            # now you are in the context of instance,
-            # `modelcontext` will return self
-            # you can define variables in several ways
-            # note, that all variables will get model's name prefix
-
-            # 3) you can create variables with Var method
-            self.Var('v1', Normal.dist(mu=mean, sd=sd))
-            # this will create variable named like '{prefix_}v1'
-            # and assign attribute 'v1' to instance
-            # created variable can be accessed with self.v1 or self['v1']
-
-            # 4) this syntax will also work as we are in the context
-            # of instance itself, names are given as usual
-            Normal('v2', mu=mean, sd=sd)
-
-            # something more complex is allowed too
-            Normal('v3', mu=mean, sd=HalfCauchy('sd', beta=10, testval=1.))
-
-            # Deterministic variables can be used in usual way
-            Deterministic('v3_sq', self.v3 ** 2)
-            # Potentials too
-            Potential('p1', tt.constant(1))
-
-    # After defining a class CustomModel you can use it in several ways
-
-    # I:
-    #   state the model within a context
-    with Model() as model:
-        CustomModel()
-        # arbitrary actions
-
-    # II:
-    #   use new class as entering point in context
-    with CustomModel() as model:
-        Normal('new_normal_var', mu=1, sd=0)
-
-    # III:
-    #   just get model instance with all that was defined in it
-    model = CustomModel()
-
-    # IV:
-    #   use many custom models within one context
-    with Model() as model:
-        CustomModel(mean=1, name='first')
-        CustomModel(mean=2, name='second')
+
+    How to define a custom model
+
+    .. code-block:: python
+
+        class CustomModel(Model):
+            # 1) override init
+            def __init__(self, mean=0, sd=1, name='', model=None):
+                # 2) call super's init first, passing model and name
+                # to it name will be prefix for all variables here if
+                # no name specified for model there will be no prefix
+                super(CustomModel, self).__init__(name, model)
+                # now you are in the context of instance,
+                # `modelcontext` will return self you can define
+                # variables in several ways note, that all variables
+                # will get model's name prefix
+
+                # 3) you can create variables with Var method
+                self.Var('v1', Normal.dist(mu=mean, sd=sd))
+                # this will create variable named like '{prefix_}v1'
+                # and assign attribute 'v1' to instance created
+                # variable can be accessed with self.v1 or self['v1']
+
+                # 4) this syntax will also work as we are in the
+                # context of instance itself, names are given as usual
+                Normal('v2', mu=mean, sd=sd)
+
+                # something more complex is allowed, too
+                half_cauchy = HalfCauchy('sd', beta=10, testval=1.)
+                Normal('v3', mu=mean, sd=half_cauchy)
+
+                # Deterministic variables can be used in usual way
+                Deterministic('v3_sq', self.v3 ** 2)
+
+                # Potentials too
+                Potential('p1', tt.constant(1))
+
+        # After defining a class CustomModel you can use it in several
+        # ways
+
+        # I:
+        #   state the model within a context
+        with Model() as model:
+            CustomModel()
+            # arbitrary actions
+
+        # II:
+        #   use new class as entering point in context
+        with CustomModel() as model:
+            Normal('new_normal_var', mu=1, sd=0)
+
+        # III:
+        #   just get model instance with all that was defined in it
+        model = CustomModel()
+
+        # IV:
+        #   use many custom models within one context
+        with Model() as model:
+            CustomModel(mean=1, name='first')
+            CustomModel(mean=2, name='second')
     """
     def __new__(cls, *args, **kwargs):
         # resolves the parent instance
@@ -738,7 +746,7 @@ def Var(self, name, dist, data=None, total_size=None):
            If data is provided, the variable is observed. If None,
            the variable is unobserved.
         total_size : scalar
-            upscales logp of variable with :math:`coef = total_size/var.shape[0]`
+            upscales logp of variable with ``coef = total_size/var.shape[0]``
 
         Returns
         -------
@@ -833,8 +841,8 @@ def __getitem__(self, key):
                 raise e
 
     def makefn(self, outs, mode=None, *args, **kwargs):
-        """Compiles a Theano function which returns `outs` and takes the variable
-        ancestors of `outs` as inputs.
+        """Compiles a Theano function which returns ``outs`` and takes the variable
+        ancestors of ``outs`` as inputs.
 
         Parameters
         ----------
@@ -853,7 +861,7 @@ def makefn(self, outs, mode=None, *args, **kwargs):
                                    mode=mode, *args, **kwargs)
 
     def fn(self, outs, mode=None, *args, **kwargs):
-        """Compiles a Theano function which returns the values of `outs`
+        """Compiles a Theano function which returns the values of ``outs``
         and takes values of model vars as arguments.
 
         Parameters
@@ -868,7 +876,7 @@ def fn(self, outs, mode=None, *args, **kwargs):
         return LoosePointFunc(self.makefn(outs, mode, *args, **kwargs), self)
 
     def fastfn(self, outs, mode=None, *args, **kwargs):
-        """Compiles a Theano function which returns `outs` and takes values
+        """Compiles a Theano function which returns ``outs`` and takes values
         of model vars as a dict as an argument.
 
         Parameters
@@ -884,7 +892,7 @@ def fastfn(self, outs, mode=None, *args, **kwargs):
         return FastPointFunc(f)
 
     def profile(self, outs, n=1000, point=None, profile=True, *args, **kwargs):
-        """Compiles and profiles a Theano function which returns `outs` and
+        """Compiles and profiles a Theano function which returns ``outs`` and
         takes values of model vars as a dict as an argument.
 
         Parameters
@@ -895,7 +903,7 @@ def profile(self, outs, n=1000, point=None, profile=True, *args, **kwargs):
         point : point
             Point to pass to the function
         profile : True or ProfileStats
-        *args, **kwargs
+        args, kwargs
             Compilation args
 
         Returns
@@ -914,10 +922,11 @@ def profile(self, outs, n=1000, point=None, profile=True, *args, **kwargs):
 
     def flatten(self, vars=None, order=None, inputvar=None):
         """Flattens model's input and returns:
-            FlatView with
+
+        FlatView with
             * input vector variable
-            * replacements `input_var -> vars`
-            * view {variable: VarMap}
+            * replacements ``input_var -> vars``
+            * view `{variable: VarMap}`
 
         Parameters
         ----------
@@ -966,7 +975,7 @@ def _repr_latex_(self, name=None, dist=None):
 
 
 def fn(outs, mode=None, model=None, *args, **kwargs):
-    """Compiles a Theano function which returns the values of `outs` and
+    """Compiles a Theano function which returns the values of ``outs`` and
     takes values of model vars as arguments.
 
     Parameters
@@ -983,7 +992,7 @@ def fn(outs, mode=None, model=None, *args, **kwargs):
 
 
 def fastfn(outs, mode=None, model=None):
-    """Compiles a Theano function which returns `outs` and takes values of model
+    """Compiles a Theano function which returns ``outs`` and takes values of model
     vars as a dict as an argument.
 
     Parameters
@@ -1005,7 +1014,7 @@ def Point(*args, **kwargs):
 
     Parameters
     ----------
-    *args, **kwargs
+    args, kwargs
         arguments to build a dict
     """
     model = modelcontext(kwargs.pop('model', None))
@@ -1361,22 +1370,22 @@ def Potential(name, var, model=None):
 
 
 class TransformedRV(TensorVariable):
+    """
+    Parameters
+    ----------
+
+    type : theano type (optional)
+    owner : theano owner (optional)
+    name : str
+    distribution : Distribution
+    model : Model
+    total_size : scalar Tensor (optional)
+        needed for upscaling logp
+    """
 
     def __init__(self, type=None, owner=None, index=None, name=None,
                  distribution=None, model=None, transform=None,
                  total_size=None):
-        """
-        Parameters
-        ----------
-
-        type : theano type (optional)
-        owner : theano owner (optional)
-        name : str
-        distribution : Distribution
-        model : Model
-        total_size : scalar Tensor (optional)
-            needed for upscaling logp
-        """
         if type is None:
             type = distribution.type
         super(TransformedRV, self).__init__(type, owner, index, name)
@@ -1427,8 +1436,8 @@ def as_iterargs(data):
 
 
 def all_continuous(vars):
-    """Check that vars not include discrete variables, excepting ObservedRVs.
-    """
+    """Check that vars not include discrete variables, excepting
+    ObservedRVs.  """
     vars_ = [var for var in vars if not isinstance(var, pm.model.ObservedRV)]
     if any([var.dtype in pm.discrete_types for var in vars_]):
         return False