Move from nbsphinx to myst-nb (#4759)

* move from nbsphinx to myst-nb
* fix some doc rendering errors
* fix fast_doc_build
* update conda envs

Author: OriolAbril

conda-envs/environment-dev-py37.yml

@@ -7,7 +7,7 @@ dependencies:
 - ipython>=7.16
 - libblas=*=*mkl
 - mkl-service
-- nbsphinx>=0.4
+- myst-nb
 - numpy=1.15
 - numpydoc>=0.9
 - pandas=0.24
@@ -16,7 +16,6 @@ dependencies:
 - pytest>=3.0
 - python-graphviz
 - python=3.7
-- recommonmark>=0.4
 - scipy=1.2
 - sphinx-autobuild>=0.7
 - sphinx>=1.5

conda-envs/environment-dev-py38.yml

@@ -7,14 +7,13 @@ dependencies:
 - ipython>=7.16
 - libblas=*=*mkl
 - mkl-service
-- nbsphinx>=0.4
+- myst-nb
 - numpydoc>=0.9
 - pre-commit>=2.8.0
 - pytest-cov>=2.5
 - pytest>=3.0
 - python-graphviz
 - python=3.8
-- recommonmark>=0.4
 - sphinx-autobuild>=0.7
 - sphinx>=1.5
 - watermark

conda-envs/environment-dev-py39.yml

@@ -7,14 +7,13 @@ dependencies:
 - ipython>=7.16
 - libblas=*=*mkl
 - mkl-service
-- nbsphinx>=0.4
+- myst-nb
 - numpydoc>=0.9
 - pre-commit>=2.8.0
 - pytest-cov>=2.5
 - pytest>=3.0
 - python-graphviz
 - python=3.9
-- recommonmark>=0.4
 - sphinx-autobuild>=0.7
 - sphinx>=1.5
 - watermark

docs/source/conf.py

@@ -1,3 +1,7 @@
+""" Sphinx configuration file.
+
+   isort:skip_file
+"""
 #!/usr/bin/env python3
 #
 # pymc3 documentation build configuration file, created by
@@ -15,13 +19,13 @@
 import os
 import sys
 
-import pymc3
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
 sys.path.insert(0, os.path.abspath("sphinxext"))
+import pymc3  # isort:skip
 
 # -- General configuration ------------------------------------------------
 
@@ -37,14 +41,13 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.mathjax",
     "sphinx.ext.intersphinx",
-    "nbsphinx",
     "numpydoc",
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.napoleon",
     "gallery_generator",
-    "recommonmark",
+    "myst_nb",
 ]
 
 # Don't auto-generate summary for class members.
@@ -72,8 +75,8 @@
 
 # General information about the project.
 project = "PyMC3"
-copyright = "2018, The PyMC Development Team"
-author = "PyMC developers"
+copyright = "2021, The PyMC Development Team"
+author = "PyMC contributors"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -101,7 +104,7 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 
-nbsphinx_execute = "never"
+jupyter_execute_notebooks = "off"
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

fast_build_docs.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-git --git-dir=docs/source/pymc-examples/.git --work-tree=docs/source/pymc-examples checkout fast-docs-build
+git --git-dir=docs/source/pymc-examples/.git --work-tree=docs/source/pymc-examples checkout main
 pushd docs/source
 make clean
 make html

pymc3/distributions/multivariate.py

@@ -531,7 +531,7 @@ class DirichletMultinomial(Discrete):
 
     .. math::
 
-    f(x \mid n, a) = \frac{\Gamma(n + 1)\Gamma(\sum a_k)}
+        f(x \mid n, a) = \frac{\Gamma(n + 1)\Gamma(\sum a_k)}
                               {\Gamma(\n + \sum a_k)}
                          \prod_{k=1}^K
                          \frac{\Gamma(x_k +  a_k)}

pymc3/distributions/timeseries.py

@@ -486,6 +486,7 @@ def random(self, point=None, size=None):
 
         Examples
         -------
+
         .. code-block:: python
 
             with pm.Model():
@@ -502,6 +503,7 @@ def random(self, point=None, size=None):
                 # draw four samples from a 2-dimensional Gaussian random walk with 10 timesteps,
                 # indexed with a (2, 2) array
                 sample = MvGaussianRandomWalk(mu, cov, shape=(10, 2)).random(size=(2, 2))
+
         """
 
         # for each draw specified by the size input, we need to draw time_steps many

pymc3/math.py

@@ -241,10 +241,9 @@ def log1mexp(x):
     https://cran.r-project.org/web/packages/Rmpfr/vignettes/log1mexp-note.pdf
 
     References
-        ----------
-        .. [Machler2012] Martin Mächler (2012).
-            "Accurately computing `\log(1-\exp(- \mid a \mid))` Assessed by the Rmpfr
-            package"
+    ----------
+    .. [Machler2012] Martin Mächler (2012).
+       "Accurately computing `\log(1-\exp(- \mid a \mid))` Assessed by the Rmpfr package"
 
     """
     return at.switch(at.lt(x, 0.6931471805599453), at.log(-at.expm1(-x)), at.log1p(-at.exp(-x)))

requirements-dev.txt

@@ -3,12 +3,11 @@
 
 h5py>=2.7
 ipython>=7.16
-nbsphinx>=0.4
+myst-nb
 numpydoc>=0.9
 pre-commit>=2.8.0
 pytest-cov>=2.5
 pytest>=3.0
-recommonmark>=0.4
 sphinx-autobuild>=0.7
 sphinx>=1.5
 watermark