Add DeprecationWarning for pystan.stan

Update docs, drop mention of stan(). Note that `DeprecationWarning`s are
not shown by default.

Closes #327.

Author: ariddell

doc/avoiding_recompilation.rst

@@ -11,8 +11,7 @@ whenever possible. If the same model is going to be used repeatedly, we would
 like to compile it just once. The following demonstrates how to reuse a model in
 different scripts and between interactive Python sessions.
 
-**Within sessions** you can avoid recompiling a model in two ways. The first
-method is to reuse a fit object in the call to ``stan``. For example,
+**Within sessions** you can avoid recompiling a model by reusing the `StanModel` instance:
 
 .. code-block:: python
 
@@ -34,32 +33,17 @@ method is to reuse a fit object in the call to ``stan``. For example,
         }
     """
 
-    data = dict(N=10, y=[0, 1, 0, 1, 0, 1, 0, 1, 1, 1])
-
-.. code-block:: python
-
-    fit = stan(model_code=model_code, data=data)
-    print(fit)
-
-    new_data = dict(N=6, y=[0, 0, 0, 0, 0, 1])
-    fit2 = stan(fit=fit, data=new_data)
-    print(fit2)
-
-However, calling ``pystan.stan`` is deprecated and will soon be removed from
-PyStan. The recommended method is to compile the model once using the
-``StanModel`` class and then sample from the model using the ``sampling``
-method.
 
 .. code-block:: python
 
     from pystan import StanModel
 
-    # using the same model as before
     data = dict(N=10, y=[0, 1, 0, 1, 0, 1, 0, 1, 1, 1])
     sm = StanModel(model_code=model_code)
     fit = sm.sampling(data=data)
     print(fit)
 
+    # reuse model with new data
     new_data = dict(N=6, y=[0, 0, 0, 0, 0, 1])
     fit2 = sm.sampling(data=new_data)
     print(fit2)
@@ -107,7 +91,7 @@ Automatically reusing models
 
 For those who miss using variables across sessions in R, it is not difficult to
 write a function that automatically saves a copy of every model that gets
-compiled using ``stan`` and opportunistically loads a copy of a model if one is
+compiled and opportunistically loads a copy of a model if one is
 available.
 
 .. code-block:: python

doc/whats_new.rst

@@ -9,6 +9,8 @@
 v2.17.0.0 (TBD)
 ===============
 - ...
+- Marked ``pystan.stan`` as deprecated. It will be removed in version 3.0. Please compile and use a
+  Stan program as two separate steps.
 
 v2.16.0.0 (22. June 2017)
 ========================

pystan/api.py

@@ -5,9 +5,10 @@
 # License. See LICENSE for a text of the license.
 #-----------------------------------------------------------------------------
 
+import hashlib
 import io
 import logging
-import hashlib
+import warnings
 
 import pystan._api  # stanc wrapper
 from pystan._compat import string_types, PY2
@@ -146,6 +147,10 @@ def stan(file=None, model_name="anon_model", model_code=None, fit=None,
          eigen_lib=None, n_jobs=-1, **kwargs):
     """Fit a model using Stan.
 
+    The `pystan.stan` function was deprecated in version 2.17 and will be
+    removed in version 3.0. Compiling and using a Stan Program (e.g., for
+    drawing samples) should be done in separate steps.
+
     Parameters
     ----------
 
@@ -368,6 +373,8 @@ def stan(file=None, model_name="anon_model", model_code=None, fit=None,
     ...     return dict(mu=1, sigma=4, z=np.random.normal(size=(3, 2)), alpha=1 + chain_id)
     >>> exfit1 = stan(model_code=excode, init=initfun2)
     """
+    warnings.warn('pystan.stan was deprecated in version 2.17 and will be removed in version 3.0. '
+                  'Compile and use a Stan program in separate steps.', DeprecationWarning)
     # NOTE: this is a thin wrapper for other functions. Error handling occurs
     # elsewhere.
     if data is None: