WIP: Documentation cleanup (#3575)

* Fix typos in docstrings.

Fix some minor wording errors, but mostly fixed formatting issues.

* Update sphinx configuration.

Updated to make a deprecation warning go away. This should not change the behavior at all.

* Update MultiTrace docs.

Minor typo fixes and added MultiTrace attributes section.

* Fix RST issues in documentation.

* Remove obsolete file.

The `getting_started.rst` file does not yield output that is linked into the docs.  Instead, the index.rst file directly links to the pages once linked from getting_started.

Author: rpgoldman

docs/source/Gaussian_Processes.rst

@@ -88,7 +88,7 @@ all columns of the matrix of inputs.
 Covariance functions in PyMC3 closely follow the algebraic rules for kernels,
 which allows users to combine covariance functions into new ones, for example:
 
-- The sum two covariance functions is also a covariance function::
+- The sum of two covariance functions is also a covariance function::
 
 
     cov_func = pm.gp.cov.ExpQuad(...) + pm.gp.cov.ExpQuad(...)
@@ -98,12 +98,14 @@ which allows users to combine covariance functions into new ones, for example:
 
     cov_func = pm.gp.cov.ExpQuad(...) * pm.gp.cov.Periodic(...)
     
-- The product (or sum) of a covariance function with a scalar is a covariance
-function::
+- The product (or sum) of a covariance function with a scalar is a
+  covariance function::
 
     
     cov_func = eta**2 * pm.gp.cov.Matern32(...)
     
+
+
 After the covariance function is defined, it is now a function that is
 evaluated by calling :code:`cov_func(x, x)` (or :code:`mean_func(x)`).  Since
 PyMC3 is built on top of Theano, it is relatively easy to define and experiment

docs/source/api.rst

@@ -1,8 +1,8 @@
 .. _api:
 
-*************
+***************
 API Reference
-*************
+***************
 
 .. toctree::
    :maxdepth: 2
@@ -24,7 +24,7 @@ API Reference
 
 
 Indices and tables
-===========
+===================
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/source/api/backends.rst

@@ -7,13 +7,6 @@ Backends
 .. automodule:: pymc3.backends
    :members:
 
-basic Backends (including MultiTrace)
-^^^^^^^^
-
-.. automodule:: pymc3.backends.base
-  :members:
-
-
 ndarray
 ^^^^^^^
 

docs/source/api/bounds.rst

@@ -72,8 +72,8 @@ Caveats
   an unnormalized probability distribution.  This doesn't effect inference
   algorithms but may complicate some model comparison procedures.
 
-API
-###
+Bounded Variable API
+####################
 
 
 .. currentmodule:: pymc3.distributions.bound

docs/source/api/gp.rst

@@ -1,5 +1,5 @@
-Gaussian Processes
-------------------
+Gaussian Processes API
+----------------------
 
 .. currentmodule:: pymc3.gp.gp
 

docs/source/api/inference.rst

@@ -14,6 +14,11 @@ Sampling
 Step-methods
 ^^^^^^^^^^^^
 
+.. currentmodule:: pymc3.sampling
+
+.. autofunction:: pymc3.sampling.assign_step_methods
+
+
 NUTS
 ~~~~
 
@@ -56,7 +61,7 @@ Sequential Monte Carlo
 
 
 MultiTrace
-^^^^^^^^
+^^^^^^^^^^
 
 .. currentmodule:: pymc3.backends.base
 .. autoclass:: pymc3.backends.base.MultiTrace
@@ -65,7 +70,7 @@ MultiTrace
 .. autoclass:: pymc3.backends.base.BaseTrace
 
 Variational Inference
-----------------
+---------------------
 
 OPVI
 ^^^^
@@ -75,8 +80,8 @@ OPVI
 .. automodule:: pymc3.variational.opvi
    :members:
 
-Inference
-^^^^^^^^^
+VI Inference API
+^^^^^^^^^^^^^^^^
 
 .. currentmodule:: pymc3.variational.inference
 

docs/source/api/model_graph.rst

@@ -1,5 +1,5 @@
 Graphing Models
--------------
+---------------
 
 .. currentmodule:: pymc3.model_graph
 .. automodule:: pymc3.model_graph

docs/source/conf.py

@@ -41,7 +41,9 @@
     "numpydoc",
     "IPython.sphinxext.ipython_console_highlighting",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.napoleon",
     "gallery_generator",
+    "recommonmark",
 ]
 
 # Don't auto-generate summary for class members.
@@ -59,7 +61,6 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
 source_suffix = [".rst", ".md"]
 
 # The encoding of source files.

docs/source/developer_guide.rst

@@ -136,6 +136,8 @@ straightforward. In a perfect world, we should have
 follows a Gaussian distribution, and
 :math:`\chi = \text{Normal}(0, 1), x \sim \chi` which define a scalar
 density function that takes input :math:`x`
+
+.. math::
     (``X:=f(x) = 1/sqrt(2*pi) * exp(-.5*x**2)``)
 
 Within a model context, RVs are essentially Theano tensors (more on that
@@ -827,8 +829,8 @@ the input to the Theano function being a 1d vector (instead of a list of
 RV that each can have very different shape), thus it is very easy to do
 matrix operation like rotation etc.
 
-Reflection
-~~~~~~~~~~
+Notes
+~~~~~
 
 | The current setup is quite powerful, as the Theano compiled function
   is fairly fast to compile and to call. Also, when we are repeatedly

docs/source/getting_started.rst

@@ -219,7 +219,7 @@ def stat_names(self):
 
 
 class MultiTrace:
-    """Main interface for accessing values from MCMC results
+    """Main interface for accessing values from MCMC results.
 
     The core method to select values is `get_values`. The method
     to select sampler statistics is `get_sampler_stats`. Both kinds of
@@ -256,6 +256,17 @@ class MultiTrace:
     For any methods that require a single trace (e.g., taking the length
     of the MultiTrace instance, which returns the number of draws), the
     trace with the highest chain number is always used.
+
+    Attributes
+    ----------
+        nchains : int
+            Number of chains in the `MultiTrace`.
+        chains : `List[int]`
+            List of chain indices
+        report : str
+            Report on the sampling process.
+        varnames : `List[str]`
+            List of variable names in the trace(s)
     """
 
     def __init__(self, straces):
@@ -363,19 +374,23 @@ def stat_names(self):
                 names.update(vars.keys())
         return names
 
-    def add_values(self, vals, overwrite=False):
-        """add variables to traces.
+    def add_values(self, vals, overwrite=False) -> None:
+        """Add variables to traces.
 
         Parameters
         ----------
         vals : dict (str: array-like)
              The keys should be the names of the new variables. The values are expected to be
-             array-like object. For traces with more than one chain the length of each value
-             should match the number of total samples already in the trace (chains * iterations),
+             array-like objects. For traces with more than one chain the length of each value
+             should match the number of total samples already in the trace `(chains * iterations)`,
              otherwise a warning is raised.
         overwrite : bool
             If `False` (default) a ValueError is raised if the variable already exists.
             Change to `True` to overwrite the values of variables
+
+        Returns
+        -------
+            Nothing.
         """
         for k, v in vals.items():
             new_var = 1

pymc3/backends/base.py

@@ -141,8 +141,8 @@ class Minibatch(tt.TensorVariable):
     if we want 1d slice of size 10 we do
     >>> x = Minibatch(data, batch_size=10)
 
-    Note, that your data is cast to `floatX` if it is not integer type
-    But you still can add `dtype` kwarg for :class:`Minibatch`
+    Note that your data is cast to `floatX` if it is not integer type
+    But you still can add the `dtype` kwarg for :class:`Minibatch`
 
     in case we want 10 sampled rows and columns
     `[(size, seed), (size, seed)]` it is

pymc3/data.py

@@ -589,8 +589,7 @@ class TruncatedNormal(BoundedContinuous):
     ========  ==========================================
     Support   :math:`x \in [a, b]`
     Mean      :math:`\mu +{\frac {\phi (\alpha )-\phi (\beta )}{Z}}\sigma`
-    Variance  :math:`\sigma ^{2}\left[1+{\frac {\alpha \phi (\alpha )-\beta \phi (\beta )}{Z}}-
-    \left({\frac {\phi (\alpha )-\phi (\beta )}{Z}}\right)^{2}\right]`
+    Variance  :math:`\sigma ^{2}\left[1+{\frac {\alpha \phi (\alpha )-\beta \phi (\beta )}{Z}}-\left({\frac {\phi (\alpha )-\phi (\beta )}{Z}}\right)^{2}\right]`
     ========  ==========================================
 
     Parameters
@@ -1544,14 +1543,14 @@ def _repr_latex_(self, name=None, dist=None):
                                                                 get_variable_name(lam))
 
     def logcdf(self, value):
-        """
+        r"""
         Compute the log of cumulative distribution function for the Exponential distribution
         at the specified value.
 
         References
         ----------
         .. [Machler2012] Martin Mächler (2012).
-            "Accurately computing log(1-exp(-|a|)) Assessed by the Rmpfr
+            "Accurately computing :math: `\log(1-\exp(-\mid a \mid))` Assessed by the Rmpfr
             package"
 
         Parameters
@@ -1758,8 +1757,9 @@ class Lognormal(PositiveContinuous):
     tau : float
         Scale parameter (tau > 0). (only required if sigma is not specified).
 
-    Example
-    -------
+    Examples
+    --------
+
     .. code-block:: python
 
         # Example to show that we pass in only `sigma` or `tau` but not both.
@@ -2931,7 +2931,7 @@ def logcdf(self, value):
         References
         ----------
         .. [Machler2012] Martin Mächler (2012).
-            "Accurately computing log(1-exp(-|a|)) Assessed by the Rmpfr
+            "Accurately computing `\log(1-\exp(- \mid a \mid))` Assessed by the Rmpfr
             package"
 
         Parameters
@@ -4060,7 +4060,7 @@ def logcdf(self, value):
         References
         ----------
         .. [Machler2012] Martin Mächler (2012).
-            "Accurately computing log(1-exp(-|a|)) Assessed by the Rmpfr
+            "Accurately computing :math:  `\log(1-\exp(- \mid a \mid<))` Assessed by the Rmpfr
             package"
 
         Parameters

pymc3/distributions/continuous.py

@@ -1535,9 +1535,10 @@ class OrderedLogistic(Categorical):
         ranges.  Do not explicitly set the first and last elements of
         :math:`c` to negative and positive infinity.
 
-    Example
+    Examples
     --------
-    .. code:: python
+
+    .. code-block:: python
 
         # Generate data for a simple 1 dimensional example problem
         n1_c = 300; n2_c = 300; n3_c = 300

pymc3/distributions/discrete.py

@@ -316,7 +316,7 @@ class EulerMaruyama(distribution.Continuous):
     sde_fn : callable
         function returning the drift and diffusion coefficients of SDE
     sde_pars : tuple
-        parameters of the SDE, passed as *args to sde_fn
+        parameters of the SDE, passed as `*args` to `sde_fn`
     """
     def __init__(self, dt, sde_fn, sde_pars, *args, **kwds):
         super().__init__(*args, **kwds)

pymc3/distributions/timeseries.py

@@ -50,10 +50,10 @@ def kron_matrix_op(krons, m, op):
 
     Parameters
     -----------
-    krons: list of square 2D array-like objects
-           D square matrices [A_1, A_2, ..., A_D] to be Kronecker'ed:
-              A = A_1 \otimes A_2 \otimes ... \otimes A_D
-           Product of column dimensions must be N
+    krons : list of square 2D array-like objects
+            D square matrices :math:`[A_1, A_2, ..., A_D]` to be Kronecker'ed
+            :math:`A = A_1 \otimes A_2 \otimes ... \otimes A_D`
+            Product of column dimensions must be :math:`N`
     m    : NxM array or 1D array (treated as Nx1)
            Object that krons act upon
     """