docs: Make edits related to 3.0 release

Make edits, mostly minor, related to 3.0 release.

- Remove reference to non-existent `to_xarray` method.
- Add developer-facing changes section to the migration guide.
- Indicate effective sample size not yet available.
- Indicate required compiler version

Closes #223

README.rst

@@ -2,8 +2,6 @@
 PyStan
 ******
 
-**NOTE: This documentation describes a BETA release of PyStan 3.**
-
 **PyStan** is a Python interface to Stan, a package for Bayesian inference.
 
 Stan® is a state-of-the-art platform for statistical modeling and
@@ -21,9 +19,7 @@ Notable features of PyStan include:
 Getting started
 ===============
 
-**NOTE: BETA versions of PyStan 3 must be installed with ``pip install --pre pystan``.**
-
-Install PyStan with ``pip install pystan``.  (PyStan requires Python 3.7 or higher running on a Linux or macOS system.)
+Install PyStan with ``pip install pystan``. PyStan requires Python ≥3.7 running on Linux or macOS. You will also need a C++ compiler such as gcc ≥9.0 or clang ≥10.0.
 
 The following block of code shows how to use PyStan with a model which studied coaching effects across eight schools (see Section 5.5 of Gelman et al (2003)). This hierarchical model is often called the "eight schools" model.
 

doc/contributing.rst

@@ -9,11 +9,11 @@ Goals:
 
 - **Power-to-weight.** Using a minimal amount of code, PyStan lets Python users access the most frequently-used features of the Stan C++ library.
 - **Timely releases.** PyStan releases appear within 72 hours of a Stan release.
-- **Minimize toil.** Maintaining PyStan should require as little time as possible. Contributions which make the software easier to maintain are welcome.
+- **Minimize toil.** In order to guarantee timely releases and rapid bug fixing, maintaining PyStan should require as little time as possible. Contributions which make the software easier to maintain are welcome.
 
 Non-goals:
 
-- **Adding new features.** Contributions which make the software more difficult to maintain are not welcome. A plug-in interface allows third-party packages to extend the software.
+- **Adding new features.** PyStan prioritizes reliability over ease of use. Contributions which make the software more difficult to maintain are not welcome. A plug-in interface allows third-party packages to extend the software.
 - **Supporting new platforms.** Adding new platforms and hardware architectures will only be considered when PyStan has an established track record of timely releases.
 
 If these goals and non-goals strike you as restrictive, we kindly remind you
@@ -54,7 +54,7 @@ git commit messages must be formatted carefully in order to allow the automatic
 You should also use the first line of your commit message to indicate the commit's "type". If it
 is a bugfix, the commit message should start with "fix:". If it is a new feature, the commit
 message should start with "feat:". This information makes reviewing patches and generating
-release notes easier. For a full list of common commit "types", consult the `Conventional Commits` specification.
+release notes easier. For a full list of common commit "types", consult the `Conventional Commits`_ specification.
 
 Commit messages must have a body.
 The body should elaborate on the summary.
@@ -67,7 +67,7 @@ In general, follow the `Astropy guidelines for git`_. Important reminders:
   should represent one logical set of changes.
 * Never merge changes from ``httpstan/main`` into your feature branch.
 
-.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary
+.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/
 .. _Astropy guidelines for git: https://astropy.readthedocs.io/en/latest/development/workflow/development_workflow.html#astropy-guidelines-for-git
 
 Contributor Covenant Code of Conduct

doc/index.rst

@@ -4,9 +4,6 @@ PyStan
 
 Release v\ |version|
 
-.. caution::
-    This documentation describes a BETA release of PyStan 3.
-
 **PyStan** is a Python interface to Stan, a package for Bayesian inference.
 
 Stan® is a state-of-the-art platform for statistical modeling and
@@ -18,7 +15,6 @@ Notable features of PyStan include:
 
 * Automatic caching of compiled Stan models
 * Automatic caching of samples from Stan models
-* An interface similar to that of RStan
 * Open source software: ISC License
 
 (Upgrading from PyStan 2? We have you covered: :ref:`upgrading`.)
@@ -28,10 +24,7 @@ Notable features of PyStan include:
 Quick start
 ===========
 
-.. tip::
-    Pre-release versions 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.)
+Install PyStan with ``python3 -m pip install pystan``. PyStan requires Python ≥3.7 running on Linux or macOS. You will also need a C++ compiler such as gcc ≥9.0 or clang ≥10.0.
 
 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)).
 

doc/installation.rst

@@ -2,14 +2,12 @@
 Installation
 ============
 
-.. tip::
-    Pre-release versions must be installed with ``python3 -m pip install --pre pystan``.
+In order to use PyStan make sure your system satisfies the requirements:
 
-In order to install PyStan make sure your system satisfies the following requirements:
-
-- Python 3.7 or higher
+- Python ≥3.7
 - Linux or macOS
 - x86-64 CPU
+- C++ compiler: gcc ≥9.0 or clang ≥10.0.
 
 Install PyStan with ``pip``. The following command will install PyStan::
 

doc/plugins.rst

@@ -1,3 +1,5 @@
+.. _plugins:
+
 =========
  Plugins
 =========

doc/upgrading.rst

@@ -4,20 +4,15 @@
 Upgrading to Newer Releases
 ===========================
 
-.. caution::
-    This section is a work-in-progress.
-
 Upgrading to 3.0
 ================
 
-**There are many backwards-incompatible changes in PyStan 3.0.**
-
-PyStan 3 is a complete rewrite. Python 3.7 or higher is required. Linux and macOS are supported.
+PyStan 3 is a complete rewrite. PyStan requires Python ≥3.7 running on Linux or macOS.
 
-PyStan 3 and RStan 3 make numerous backwards-incompatible changes.
+PyStan 3 makes numerous **backwards-incompatible changes**.
 Many of these changes are introduced to harmonize variable naming practices across the numerous interfaces to the Stan C++ library.
 
-The scope of PyStan 3 is reduced. The default HMC sampler is supported. Variational inference, for example, is no longer supported.
+The scope of PyStan 3 is reduced in the interest of freeing up resources to dedicate to making the software more reliable and to guaranteeing timely releases. The default HMC sampler is supported. Variational inference, for example, is no longer supported.
 
 PyStan 3 users aware of changes in variable, function, and method names should be able to upgrade without much difficulty. The basic programming "flow" is essentially unchanged.
 
@@ -34,7 +29,7 @@ Here's how we draw from the posterior distribution in the eight schools model us
     fit = posterior.sample(num_chains=4, num_samples=1000)
     fit["eta"]  # array with shape (8, 4000)
 
-Compare this with the equivalent PyStan 2 code:
+Compare this with similar PyStan 2 code:
 
 .. code-block:: python
 
@@ -51,11 +46,11 @@ Notable changes
 ---------------
 
 - Use ``import stan`` instead of ``import pystan``.
-- Data and random seed are provided earlier, in the build phase. Previously these were provided before sampling.
+- Data and random seed are provided earlier, to the ``build`` method. Previously these were provided before sampling.
 - Use ``num_samples`` to indicate number of desired draws.
 - Use ``fit["param"]`` instead of ``fit.extract()["param"]``. The shape of the array returned will be different.
 - Draws are returned in a shape which reflects their shape in the Stan model. Number of draws is the trailing index.
-- The "stansummary" display is no longer supported. Effective sample size, however, is available.
-- License is now ISC. Previously GPL3 was used.
+- The "stansummary" display is no longer supported. Support for displaying effective sample size is planned.
+- The ``check_hmc_diagnostics`` function is removed. Support for :ref:`plugins <plugins>` has been added to allow for the development of a replacement. The function was removed from PyStan because it is not part of the Stan C++ library.
 - Microsoft Windows is not supported in PyStan 3. It was (partially) supported in PyStan 2.
 - The default, recommended HMC sampler is fully supported. Variational inference, maximization algorithms, and other sampling algorithms are not supported. Users who need these features should consider using different software (e.g., CmdStan, CmdStanPy, jax, PyTorch).

stan/fit.py

@@ -11,8 +11,8 @@ class Fit(collections.abc.Mapping):
 
     Returned by methods of a ``Model``. Users will not instantiate this class directly.
 
-    A `Fit` instance works like a Python dictionary. Other user-friendly views of draws
-    are available via the ``to_frame`` and ``to_xarray`` methods.
+    A `Fit` instance works like a Python dictionary. A user-friendly views of draws
+    is available via ``to_frame``.
 
     """