docs: Add several clarifications

Mention need to use `pip install --pre`. Mention that
pandas is not installed by default. Fix code highlighting issue.

Closes #124

doc/getting_started.rst

@@ -70,3 +70,5 @@ Alternatively, we can extract all variables into a pandas DataFrame.
 .. code-block:: python
 
     df = fit.to_frame()
+
+Using the ``to_frame()`` method requires pandas. (Installing ``pystan`` will not install ``pandas``.) Install pandas with ``python3 -m pip install pandas``.

doc/index.rst

@@ -25,6 +25,8 @@ Notable features of PyStan include:
 Quickstart
 ==========
 
+**NOTE: Pre-release version must be installed with ``python3 -m pip install --pre pystan``.**
+
 Install PyStan with ``python3 -m pip install pystan``. (PyStan requires Python 3.7 or higher running on a Linux or macOS system.)
 
 This block of code shows how to use PyStan with a hierarchical model used to study coaching effects across eight schools (see Section 5.5 of Gelman et al. (2003)).
@@ -60,7 +62,7 @@ This block of code shows how to use PyStan with a hierarchical model used to stu
     posterior = stan.build(schools_code, data=schools_data)
     fit = posterior.sample(num_chains=4, num_samples=1000)
     eta = fit["eta"]  # array with shape (8, 4000)
-    df = fit.to_frame()  # pandas `DataFrame`
+    df = fit.to_frame()  # pandas `DataFrame, requires pandas
 
 
 Documentation

doc/installation.rst

@@ -2,6 +2,8 @@
 Installation
 ============
 
+**NOTE: Pre-release version must be installed with ``python3 -m pip install --pre pystan``.**
+
 In order to install PyStan make sure your system satisfies the following requirements:
 
 - Python 3.7 or higher

doc/upgrading.rst

@@ -16,25 +16,25 @@ PyStan 3 users aware of changes in variable, function, and method names should b
 
 Here's how we draw from the posterior distribution in the eight schools model using PyStan 3:
 
-::
+.. code-block:: python
 
     import stan
 
-    schools_code = """data { …"""
-    schools_data = {'J': 8, … }
+    schools_code = """data { ..."""
+    schools_data = {'J': 8, ... }
 
     posterior = stan.build(schools_code, data=schools_data, random_seed=1)
     fit = posterior.sample(num_chains=4, num_samples=1000)
     fit["eta"]  # array with shape (8, 4000)
 
 Compare this with the equivalent PyStan 2 code:
 
-::
+.. code-block:: python
 
     import pystan
 
-    schools_code = """data { …"""
-    schools_data = {'J': 8, … }
+    schools_code = """data { ..."""
+    schools_data = {'J': 8, ... }
 
     sm = pystan.StanModel(model_code=schools_code)
     fit = sm.sampling(data=schools_data, iter=1000, chains=4, seed=1)