diff --git a/.gitignore b/.gitignore index 6a2f23cc96..2c9cee8435 100644 --- 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 b/Makefile similarity index 97% rename from docs/source/Makefile rename to Makefile index 219e6c9068..03bf8f34be 100644 --- a/docs/source/Makefile +++ b/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 index 5a8daee222..c52f1b5969 100644 --- 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 `. +library, a general purpose library for +"exploratory analysis of Bayesian models". + +* Functions from the `arviz.plots` module are available through ``pymc.`` or ``pymc.plots.``, +but for their API documentation please refer to the :ref:`ArviZ documentation `. + +* Functions from the `arviz.stats` module are available through ``pymc.`` or ``pymc.stats.``, +but for their API documentation please refer to the :ref:`ArviZ documentation `. + +ArviZ is a dependency of PyMC and so, in addition to the locations described above, +importing ArviZ and using ``arviz.`` will also work without any extra installation. + +Generalized Linear Models (GLMs) +-------------------------------- + +Generalized Linear Models are delegated to the +`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 index 6deacb2549..8a5ce87621 100644 --- 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 index 363bb0cb46..fc8faf8962 100644 --- 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 index 9260123dad..50a34ff8b2 100644 --- 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 index 8c25761a2f..85e3bee026 100644 --- 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 index aa8385a410..831aaa5990 100644 --- 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 index 44c0bb8454..fa79d5566d 100644 --- a/docs/source/api/distributions/timeseries.rst +++ b/docs/source/api/distributions/timeseries.rst @@ -2,8 +2,10 @@ Timeseries ********** -.. currentmodule:: pymc.distributions.timeseries +.. currentmodule:: pymc .. autosummary:: + :toctree: generated + AR1 AR GaussianRandomWalk @@ -11,6 +13,3 @@ Timeseries EulerMaruyama MvGaussianRandomWalk MvStudentTRandomWalk - -.. automodule:: pymc.distributions.timeseries - :members: diff --git a/docs/source/api/distributions/transforms.rst b/docs/source/api/distributions/transforms.rst index ef3cf4a048..8a08baca4f 100644 --- 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 index 022308aea2..441eca24a6 100644 --- 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 deleted file mode 100644 index 051d2582db..0000000000 --- a/docs/source/api/glm.rst +++ /dev/null @@ -1,10 +0,0 @@ -******************************** -Generalized Linear Models (GLMs) -******************************** - -.. currentmodule:: pymc.glm.linear - -Generalized Linear Models are delegated to the -`Bambi `_. -library, a high-level Bayesian model-building -interface built on top of the PyMC. diff --git a/docs/source/api/plots.rst b/docs/source/api/plots.rst deleted file mode 100644 index fd7fb8220b..0000000000 --- a/docs/source/api/plots.rst +++ /dev/null @@ -1,13 +0,0 @@ -***** -Plots -***** - -.. currentmodule:: pymc.plots - -Plots are delegated to the -`ArviZ `_. -library, a general purpose library for -"exploratory analysis of Bayesian models". - -Functions from the `arviz.plots` module are available through ``pymc.`` or ``pymc.plots.``, -but for their API documentation please refer to the :ref:`ArviZ documentation `. diff --git a/docs/source/api/stats.rst b/docs/source/api/stats.rst deleted file mode 100644 index bafa5cca56..0000000000 --- a/docs/source/api/stats.rst +++ /dev/null @@ -1,13 +0,0 @@ -***** -Stats -***** - -.. currentmodule:: pymc.stats - -Statistics and diagnostics are delegated to the -`ArviZ `_. -library, a general purpose library for -"exploratory analysis of Bayesian models". - -Functions from the `arviz.stats` module are available through ``pymc.`` or ``pymc.stats.``, -but for their API documentation please refer to the :ref:`ArviZ documentation `. diff --git a/docs/source/conf.py b/docs/source/conf.py index d4f5dcdf37..6419abb8ef 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -118,7 +118,7 @@ # myst and panels config jupyter_execute_notebooks = "off" myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath", "substitution"] -panels_add_bootstrap_css = False +myst_heading_anchors = None # The reST default role (used for this markup: `text`) to use for all # documents. @@ -151,6 +151,7 @@ intersphinx_mapping = { "arviz": ("https://arviz-devs.github.io/arviz/", None), "aesara": ("https://aesara.readthedocs.io/en/latest/", None), + "aeppl": ("https://aesara-devs.github.io/aeppl/", None), "numpy": ("https://numpy.org/doc/stable/", None), "nb": ("https://pymc-examples.readthedocs.io/en/latest/", None), } @@ -191,7 +192,6 @@ "navbar_end": ["search-field.html", "navbar-icon-links.html"], "search_bar_text": "Search...", "use_edit_page_button": False, # TODO: see how to skip of fix for generated pages - "externalrefs": True, "google_analytics_id": "UA-176578023-1", } html_context = { diff --git a/docs/source/contributing/build_docs.md b/docs/source/contributing/build_docs.md index 218ebff5ed..9fce38c25b 100644 --- a/docs/source/contributing/build_docs.md +++ b/docs/source/contributing/build_docs.md @@ -2,13 +2,21 @@ To build the docs, run these commands at pymc repository root: -TODO: fix makefile - ```bash $ pip install -r requirements-dev.txt # Make sure the dev requirements are installed -$ cd docs/source -$ make html # Build docs -$ python -m http.server --directory ../_build/html # Render docs +$ make clean # clean built docs from previous runs and intermediate outputs +$ make html # Build docs +$ python -m http.server --directory ../_build/ # Render docs ``` Check the printed url where docs are being served and open it. + +The `make clean` step is not always necessary, if you are working on a specific page +for example, you can rebuild the docs without the clean step and everything should +work fine. If you are restructuring the content or editing toctrees, then you'll need +to execute `make clean`. + +A good approach is to skip the `make clean`, which makes +the `make html` blazing fast and see how everything looks. +If something looks strange, run `make clean` and `make html` one after the other +to see if it fixes the issue before checking anything else. diff --git a/docs/source/index.md b/docs/source/index.md index a1401acba9..7b8edee0d6 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -143,7 +143,7 @@ Use this to cite the library: Salvatier J., Wiecki T.V., Fonnesbeck C. (2016) Probabilistic programming in Python using PyMC3. PeerJ Computer Science 2:e55 [DOI: 10.7717/peerj-cs.55.](https://doi.org/10.7717/peerj-cs.55) -For detailed advise on citing PyMC go to {ref +For detailed advise on citing PyMC go to {ref}`citing_pymc`. See [Google Scholar](https://scholar.google.de/scholar?oi=bibs&hl=en&authuser=1&cites=6936955228135731011) for a continuously updated list of papers citing PyMC3. :::{toctree} diff --git a/docs/source/make.bat b/make.bat similarity index 100% rename from docs/source/make.bat rename to make.bat diff --git a/pymc/distributions/transforms.py b/pymc/distributions/transforms.py index 757c26bec7..9b750ac7c9 100644 --- a/pymc/distributions/transforms.py +++ b/pymc/distributions/transforms.py @@ -157,10 +157,38 @@ def log_jac_det(self, value, *inputs): simplex = Simplex() + logodds = LogOddsTransform() +logodds.__doc__ = """ +Instantiation of :class:`aeppl.transforms.LogOddsTransform` +for use in the ``transform`` argument of a random variable.""" + interval = IntervalTransform +interval.__doc__ = """ +Instantiation of :class:`aeppl.transforms.IntervalTransform` +for use in the ``transform`` argument of a random variable.""" + log_exp_m1 = LogExpM1() +log_exp_m1.__doc__ = """ +Instantiation of :class:`pymc.transforms.LogExpM1` +for use in the ``transform`` argument of a random variable.""" + ordered = Ordered() +ordered.__doc__ = """ +Instantiation of :class:`pymc.transforms.Ordered` +for use in the ``transform`` argument of a random variable.""" + log = LogTransform() +log.__doc__ = """ +Instantiation of :class:`aeppl.transforms.LogTransform` +for use in the ``transform`` argument of a random variable.""" + sum_to_1 = SumTo1() +sum_to_1.__doc__ = """ +Instantiation of :class:`pymc.transforms.SumTo1` +for use in the ``transform`` argument of a random variable.""" + circular = CircularTransform() +circular.__doc__ = """ +Instantiation of :class:`aeppl.transforms.CircularTransform` +for use in the ``transform`` argument of a random variable.""" diff --git a/pymc/model.py b/pymc/model.py index 4dcb20f16c..1029e3eb47 100644 --- a/pymc/model.py +++ b/pymc/model.py @@ -515,9 +515,9 @@ class Model(Factor, WithMemoization, metaclass=ContextMeta): """Encapsulates the variables and likelihood factors of a model. Model class can be used for creating class based models. To create - a class based model you should inherit from :class:`~.Model` and - override :meth:`~.__init__` with arbitrary definitions (do not - forget to call base class :meth:`__init__` first). + a class based model you should inherit from :class:`~pymc.Model` and + override the `__init__` method with arbitrary definitions (do not + forget to call base class :meth:`pymc.Model.__init__` first). Parameters ---------- @@ -600,6 +600,7 @@ def __init__(self, mean=0, sigma=1, name=''): with Model() as model: CustomModel(mean=1, name='first') CustomModel(mean=2, name='second') + """ if TYPE_CHECKING: