docs: minor doc updates, fixes

stan-dev · Dec 11, 2018 · b7929d3 · b7929d3
1 parent 01fd4b1
commit b7929d3
Show file tree

Hide file tree

Showing 15 changed files with 71 additions and 74 deletions.
diff --git a/README.rst b/README.rst
@@ -14,6 +14,12 @@ and physical sciences, engineering, and business.
 
 * Open source software: ISC License
 
+Installation
+============
+
+There is no public release of PyStan 3. You should install from source.
+
+
 Getting Started
 ===============
 
@@ -54,9 +60,3 @@ coaching effects from eight schools. For simplicity, we call this example
     fit = posterior.sample(num_chains=4, num_samples=1000)
     eta = fit["eta"]  # array with shape (8, 4000)
     df = fit.to_frame()  # pandas `DataFrame`
-
-
-Installation
-============
-
-Install from source in a virtualenv.
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
diff --git a/doc/source/developers.rst b/doc/source/developers.rst
@@ -0,0 +1,6 @@
+Developer Resources
+===================
+
+Documents for PyStan developers are collected here:
+
+- :ref:`release-howto`
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -1,13 +1,7 @@
-.. pystan documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to PyStan's documentation!
 ==================================
 
-**NOTE: This is an experimental version of PyStan 3. Do not use! If you must use this, install
-it in a virtualenv so it will not conflict with Pystan 2.x.**
+**NOTE: This is an experimental version of PyStan. Do not use!**
 
 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,17 +12,17 @@ and physical sciences, engineering, and business.
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   getting_started
-   install/index
-   library/index
-   contributor/index
+   installation
+   usage
+   whats_new
+   contributing
+   developers
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
@@ -0,0 +1,6 @@
+============
+Installation
+============
+
+There is no public release of PyStan 3. You should install from source.
+
diff --git a/doc/source/library/index.rst b/doc/source/library/index.rst
diff --git a/doc/source/release-howto.rst b/doc/source/release-howto.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+.. _release-howto:
+
+===============
+ Release HOWTO
+===============
+
+*This document is intended for PyStan developers.*
+
+TODO
diff --git a/doc/source/getting_started.rst → doc/source/usage.rst b/doc/source/getting_started.rst → doc/source/usage.rst
@@ -1,6 +1,6 @@
-=================
- Getting Started
-=================
+=====
+Usage
+=====
 
 This is an example in Section 5.5 of Gelman et al (2003), which studied
 coaching effects from eight schools. For simplicity, we call this example
@@ -37,4 +37,17 @@ coaching effects from eight schools. For simplicity, we call this example
 
     posterior = stan.build(program_code, data=data)
     fit = posterior.sample(num_chains=4, num_samples=1000)
-    df = fit.to_frame()  # yields a pandas `DataFrame`
+    eta = fit["eta"]  # array with shape (8, 4000)
+    df = fit.to_frame()  # pandas `DataFrame`
+
+
+
+
+Reference
+=========
+
+.. automodule:: stan
+   :members: build
+
+.. automodule:: stan.model
+   :members: Model
diff --git a/doc/source/whats_new.rst b/doc/source/whats_new.rst
@@ -0,0 +1,10 @@
+.. _whats_new:
+
+.. currentmodule:: stan
+
+============
+ What's New
+============
+
+3.0.0 (TBA)
+===========
diff --git a/setup.cfg b/setup.cfg
@@ -10,6 +10,7 @@ classifier =
     Programming Language :: Python
     Programming Language :: Python :: 3
     Programming Language :: Python :: 3.6
+license_file = LICENSE
 
 [files]
 packages =
@@ -20,6 +21,3 @@ all-files = 1
 warning-is-error = 1
 source-dir = doc/source
 build-dir = doc/build
-
-[upload_sphinx]
-upload-dir = doc/build/html
diff --git a/stan/fit.py b/stan/fit.py
@@ -8,10 +8,12 @@
 class Fit:
     """Stores draws from one or more chains.
 
-    The `values` attribute provides direct access to draws. More user-friendly
-    presentations of draws are available via the `to_frame` and `to_xarray`
+    The ``values`` attribute provides direct access to draws. More user-friendly
+    presentations of draws are available via the ``to_frame`` and ``to_xarray``
     methods.
 
+    Returned by methods of a ``Model``. Users will not instantiate this class directly.
+
     Attributes:
         values: An ndarray with shape (num_sample_and_sampler_params + num_flat_params, num_draws, num_chains)
 

diff --git a/stan/model.py b/stan/model.py
@@ -16,7 +16,7 @@
 class Model:
     """Stores data associated with and proxies calls to a Stan model.
 
-    Returned by `build`. Users will not instantiate this class directly.
+    Returned by ``build``. Users will not instantiate this class directly.
 
     """
 
@@ -43,7 +43,7 @@ def __init__(
     def sample(self, **kwargs):
         """Draw samples from the model.
 
-        Parameters in `kwargs` will be passed to the default sample function in
+        Parameters in ``kwargs`` will be passed to the default sample function in
         stan::services. Parameter names are identical to those used in CmdStan.
         See the CmdStan documentation for parameter descriptions and default
         values.