Refactor Bound distribution

Author: kc611

RELEASE-NOTES.md

@@ -9,6 +9,7 @@
 - The `Distribution` keyword argument `testval` has been deprecated in favor of `initval`. Furthermore `initval` no longer assigns a `tag.test_value` on tensors since the initial values are now kept track of by the model object ([see #4913](https://github.com/pymc-devs/pymc3/pull/4913)).
 - `pm.sample` now returns results as `InferenceData` instead of `MultiTrace` by default (see [#4744](https://github.com/pymc-devs/pymc3/pull/4744)).
 - `pm.sample_prior_predictive` no longer returns transformed variable values by default. Pass them by name in `var_names` if you want to obtain these draws (see [4769](https://github.com/pymc-devs/pymc3/pull/4769)).
+- ⚠ `pm.Bound` interface no longer accepts a callable class as argument, instead it requires an instantiated distribution (created via the `.dist()` API) to be passed as an argument. In addition, Bound no longer returns a class instance but works as a normal PyMC3 distribution. Finally, it is no longer possible to do predictive random sampling from Bounded variables. Please, consult the new documentation for details on how to use Bounded variables (see [4815](https://github.com/pymc-devs/pymc3/pull/4815)).
 - ...
 
 ### New Features

docs/source/api/bounds.rst

@@ -6,10 +6,6 @@ PyMC3 includes the construct :class:`~pymc3.distributions.bound.Bound` for
 placing constraints on existing probability distributions.  It modifies a given
 distribution to take values only within a specified interval.
 
-Note that the `Bound` class does *not* directly create a bounded
-distribution: instead it creates a Callable class that can be
-*invoked* to create a bounded distribution, as the example below illustrates.
-
 Some types of variables require constraints.  For instance, it doesn't make
 sense for a standard deviation to have a negative value, so something like a
 Normal prior on a parameter that represents a standard deviation would be
@@ -38,28 +34,8 @@ specification of a bounded distribution should go within the model block::
     import pymc3 as pm
 
     with pm.Model() as model:
-        BoundedNormal = pm.Bound(pm.Normal, lower=0.0)
-        x = BoundedNormal('x', mu=1.0, sigma=3.0)
-
-If the bound will be applied to a single variable in the model, it may be
-cleaner notationally to define both the bound and variable together. ::
-
-    with model:
-        x = pm.Bound(pm.Normal, lower=0.0)('x', mu=1.0, sigma=3.0)
-
-However, it is possible to create multiple different random variables
-that have the same bound applied to them::
-
-    with model:
-        BoundNormal = pm.Bound(pm.Normal, lower=0.0)
-        hyper_mu = BoundNormal("hyper_mu", mu=1, sigma=0.5)
-        mu = BoundNormal("mu", mu=hyper_mu, sigma=1)
-
-Bounds can also be applied to a vector of random variables.  With the same
-``BoundedNormal`` object we created previously we can write::
-
-    with model:
-        x_vector = BoundedNormal('x_vector', mu=1.0, sigma=3.0, shape=3)
+        norm = Normal.dist(mu=1.0, sigma=3.0)
+        x = Bound('x', norm, lower=0.0)
 
 Caveats
 #######