pymc-devs · michaelosthege · Dec 18, 2021 · Dec 16, 2021 · Dec 16, 2021 · Dec 16, 2021
diff --git a/.gitignore b/.gitignore
@@ -18,6 +18,7 @@ tags
 # Sphinx
 _build
 docs/jupyter_execute
+docs/**/generated/*
 
 # Merge tool
 *.orig

diff --git a/docs/source/Makefile → Makefile b/docs/source/Makefile → Makefile
@@ -5,7 +5,8 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+SOURCEDIR     = docs/source
+BUILDDIR      = docs/_build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -51,9 +52,11 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(SOURCEDIR)/api/**/generated
+	rm -rf docs/jupyter_execute
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -15,11 +15,34 @@ API Reference
    api/smc
    api/step_methods
    api/inference
-   api/plots
 
-Indices and tables
-===================
+--------------
+API extensions
+--------------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Plots, stats and diagnostics
+----------------------------
+Plots, stats and diagnostics are delegated to the
+:doc:`ArviZ <arviz:index>`.
+library, a general purpose library for
+"exploratory analysis of Bayesian models".
+
+* Functions from the `arviz.plots` module are available through ``pymc.<function>`` or ``pymc.plots.<function>``,
+but for their API documentation please refer to the :ref:`ArviZ documentation <arviz:plot_api>`.
+
+* Functions from the `arviz.stats` module are available through ``pymc.<function>`` or ``pymc.stats.<function>``,
+but for their API documentation please refer to the :ref:`ArviZ documentation <arviz:stats_api>`.
+
+ArviZ is a dependency of PyMC and so, in addition to the locations described above,
+importing ArviZ and using ``arviz.<function>`` will also work without any extra installation.
+
+Generalized Linear Models (GLMs)
+--------------------------------
+
+Generalized Linear Models are delegated to the
+`Bambi <https://bambinos.github.io/bambi>`_.
+library, a high-level Bayesian model-building
+interface built on top of PyMC.
+
+Bambi is not a dependency of PyMC and should be installed in addition to PyMC
+to use it to generate PyMC models via formula syntax.
diff --git a/docs/source/api/distributions/continuous.rst b/docs/source/api/distributions/continuous.rst
@@ -2,8 +2,9 @@
 Continuous
 **********
 
-.. currentmodule:: pymc.distributions.continuous
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated/
 
    Uniform
    Flat
@@ -38,6 +39,3 @@ Continuous
    Moyal
    AsymmetricLaplace
    PolyaGamma
-
-.. automodule:: pymc.distributions.continuous
-   :members:
diff --git a/docs/source/api/distributions/discrete.rst b/docs/source/api/distributions/discrete.rst
@@ -2,8 +2,9 @@
 Discrete
 ********
 
-.. currentmodule:: pymc.distributions.discrete
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated
 
    Binomial
    BetaBinomial
@@ -21,6 +22,3 @@ Discrete
    Categorical
    OrderedLogistic
    OrderedProbit
-
-.. automodule:: pymc.distributions.discrete
-   :members:
diff --git a/docs/source/api/distributions/mixture.rst b/docs/source/api/distributions/mixture.rst
@@ -2,11 +2,10 @@
 Mixture
 *******
 
-.. currentmodule:: pymc.distributions.mixture
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated
+
    Mixture
    NormalMixture
    MixtureSameFamily
-
-.. automodule:: pymc.distributions.mixture
-   :members:
diff --git a/docs/source/api/distributions/multivariate.rst b/docs/source/api/distributions/multivariate.rst
@@ -2,8 +2,9 @@
 Multivariate
 ************
 
-.. currentmodule:: pymc.distributions.multivariate
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated
 
    MvNormal
    MvStudentT
@@ -18,6 +19,3 @@ Multivariate
    MatrixNormal
    KroneckerNormal
    CAR
-
-.. automodule:: pymc.distributions.multivariate
-   :members:
diff --git a/docs/source/api/distributions/simulator.rst b/docs/source/api/distributions/simulator.rst
@@ -2,12 +2,10 @@
 Simulator
 **********
 
-.. currentmodule:: pymc.distributions.simulator
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated
 
    SimulatorRV
    Simulator
    KullbackLiebler
-
-.. automodule:: pymc.distributions.simulator
-   :members:
diff --git a/docs/source/api/distributions/timeseries.rst b/docs/source/api/distributions/timeseries.rst
@@ -2,15 +2,14 @@
 Timeseries
 **********
 
-.. currentmodule:: pymc.distributions.timeseries
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated
+
     AR1
     AR
     GaussianRandomWalk
     GARCH11
     EulerMaruyama
     MvGaussianRandomWalk
     MvStudentTRandomWalk
-
-.. automodule:: pymc.distributions.timeseries
-   :members:
diff --git a/docs/source/api/distributions/transforms.rst b/docs/source/api/distributions/transforms.rst
@@ -1,129 +1,42 @@
-****************************************************************
-Transformations of a random variable from one space to another
-****************************************************************
-
-Note that for convenience these entities can be addressed as
-``pm.transforms.``\ *X* for any name *X*, although they are actually
-implemented as ``pm.distributions.transforms.``\ *X*.
-
-.. currentmodule:: pymc.distributions.transforms
-
-
-.. contents ::
-
-..
-   .. autosummary::
-
-   Transform
-   stick_breaking
-   logodds
-   interval
-   log_exp_m1
-   ordered
-   log
-   sum_to_1
-   circular
-   CholeskyCovPacked
-   Chain
-
+***************
+Transformations
+***************
 
+.. currentmodule:: pymc.transforms
 
 Transform Instances
 ~~~~~~~~~~~~~~~~~~~
 
 Transform instances are the entities that should be used in the
-``transform`` parameter to a random variable constructor.  These are
-initialized instances of the Transform Classes, which are described
-below.
-
-.. glossary::
-
-``stick_breaking``
-    Instantiation of :class:`~pymc.distributions.transforms.StickBreaking`
-    :class:`~pymc.distributions.transforms.Transform` class for use in the ``transform``
-    argument of a random variable.
-
-``logodds``
-    Instantiation of
-    :class:`~pymc.distributions.transforms.LogOdds` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-``interval``
-    Alias of
-    :class:`~pymc.distributions.transforms.Interval` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-``log_exp_m1``
-    Instantiation of
-    :class:`~pymc.distributions.transforms.LogExpM1` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
+``transform`` parameter to a random variable constructor.
 
-``lowerbound``
-    Alias of
-    :class:`~pymc.distributions.transforms.LowerBound` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-``upperbound``
-    Alias of
-    :class:`~pymc.distributions.transforms.UpperBound` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-``ordered``
-    Instantiation of
-    :class:`~pymc.distributions.transforms.Ordered` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-``log``
-    Instantiation of
-    :class:`~pymc.distributions.transforms.Log` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-
-``sum_to_1``
-    Instantiation of
-    :class:`~pymc.distributions.transforms.SumTo1` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-
-``circular``
-    Instantiation of
-    :class:`~pymc.distributions.transforms.Circular` :class:`~pymc.distributions.transforms.Transform` class
-    for use in the ``transform`` argument of a random variable.
-
-Transform Base Classes
-~~~~~~~~~~~~~~~~~~~~~~
-
-Typically the programmer will not use these directly.
-
-.. autoclass::  Transform
-    :members:
+.. autosummary::
+   :toctree: generated
 
+    simplex
+    logodds
+    interval
+    log_exp_m1
+    ordered
+    log
+    sum_to_1
+    circular
 
 Transform Composition Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: Chain
-    :members:
-.. autoclass:: CholeskyCovPacked
-    :members:
+.. autosummary::
+   :toctree: generated
 
+    Chain
+    CholeskyCovPacked
 
 Specific Transform Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass::  Log
-    :members:
-.. autoclass::  LogExpM1
-    :members:
-.. autoclass::  LogOdds
-    :members:
-.. autoclass::  Interval
-    :members:
-.. autoclass::  Ordered
-    :members:
-.. autoclass::  SumTo1
-    :members:
-.. autoclass::  StickBreaking
-    :members:
-.. autoclass::  Circular
-    :members:
+.. autosummary::
+   :toctree: generated
+
+    LogExpM1
+    Ordered
+    SumTo1
diff --git a/docs/source/api/distributions/utilities.rst b/docs/source/api/distributions/utilities.rst
@@ -1,19 +1,13 @@
-*******************************************
-Distribution utility classes and functions
-*******************************************
+**********************
+Distribution utilities
+**********************
 
-.. currentmodule:: pymc.distributions
+.. currentmodule:: pymc
 .. autosummary::
+   :toctree: generated/
 
-  Distribution
-  Discrete
-  Continuous
-  NoDistribution
-  DensityDist
-
-.. autoclass:: Distribution
-.. autoclass:: Discrete
-.. autoclass:: Continuous
-.. autoclass:: NoDistribution
-.. autoclass:: DensityDist
-    :members:
+    Distribution
+    Discrete
+    Continuous
+    NoDistribution
+    DensityDist
diff --git a/docs/source/api/glm.rst b/docs/source/api/glm.rst
diff --git a/docs/source/api/plots.rst b/docs/source/api/plots.rst
diff --git a/docs/source/api/stats.rst b/docs/source/api/stats.rst