Fix documentation errors (blackjax-devs#158)

* Add requirements files for documentation

* Fix references in documentation

Author: rlouf

.github/workflows/build_doc.yml

@@ -21,7 +21,7 @@ jobs:
 
       - name: Build docs
         run: |
-          pip install -r requirements-dev.txt
+          pip install -r requirements-doc.txt
           sphinx-build -b html docs docs/build/html
 
       - name: Publish docs

blackjax/adaptation/step_size.py

@@ -74,21 +74,21 @@ def dual_averaging_adaptation(
     :math:`h(\\overline{x}_t)` converges to 0, i.e. the Metropolis acceptance
     rate converges to the desired rate.
 
-    See reference [Hoffman2014]_ (section 3.2.1) for a detailed discussion.
+    See reference [Hoffman2014a]_ (section 3.2.1) for a detailed discussion.
 
     Parameters
     ----------
     t0: float >= 0
         Free parameter that stabilizes the initial iterations of the algorithm.
-        Large values may slow down convergence. Introduced in [Hoffman2014]_ with a default
+        Large values may slow down convergence. Introduced in [Hoffman2014a]_ with a default
         value of 10.
     gamma:
-        Controls the speed of convergence of the scheme. The authors of [Hoffman2014]_ recommend
+        Controls the speed of convergence of the scheme. The authors of [Hoffman2014a]_ recommend
         a value of 0.05.
     kappa: float in ]0.5, 1]
         Controls the weights of past steps in the current update. The scheme will
         quickly forget earlier step for a small value of `kappa`. Introduced
-        in [Hoffman2014]_, with a recommended value of .75
+        in [Hoffman2014a]_, with a recommended value of .75
     target:
         Target acceptance rate.
 
@@ -104,7 +104,7 @@ def dual_averaging_adaptation(
 
     .. [Nesterov2009] Nesterov, Yurii. "Primal-dual subgradient methods for convex
             problems." Mathematical programming 120.1 (2009): 221-259.
-    .. [Hoffman2014] Hoffman, Matthew D., and Andrew Gelman. "The No-U-Turn sampler:
+    .. [Hoffman2014a] Hoffman, Matthew D., and Andrew Gelman. "The No-U-Turn sampler:
            adaptively setting path lengths in Hamiltonian Monte Carlo." Journal
            of Machine Learning Research 15.1 (2014): 1593-1623.
     """
@@ -183,7 +183,7 @@ def find_reasonable_step_size(
     value for the step size starting from any value, choosing a good first
     value can speed up the convergence. This heuristics doubles and halves the
     step size until the acceptance probability of the HMC proposal crosses the
-    target value [Hoffman2014]_.
+    target value [Hoffman2014b]_.
 
     Parameters
     ----------
@@ -210,7 +210,7 @@ def find_reasonable_step_size(
 
     References
     ----------
-    .. [Hoffman2014] Hoffman, Matthew D., and Andrew Gelman. "The No-U-Turn sampler:
+    .. [Hoffman2014b] Hoffman, Matthew D., and Andrew Gelman. "The No-U-Turn sampler:
            adaptively setting path lengths in Hamiltonian Monte Carlo." Journal
            of Machine Learning Research 15.1 (2014): 1593-1623.
 

blackjax/diagnostics.py

@@ -37,12 +37,12 @@ def potential_scale_reduction(
     where :math:`W` is the within-chain variance and :math:`\\hat{V}` is the posterior variance
     estimate for the pooled traces. This is the potential scale reduction factor, which
     converges to unity when each of the traces is a sample from the target posterior. Values
-    greater than one indicate that one or more chains have not yet converged.
+    greater than one indicate that one or more chains have not yet converged [StanRhat]_ [Gelman1992]_.
 
     References
     ----------
-    .. [1] https://mc-stan.org/docs/2_27/reference-manual/notation-for-samples-chains-and-draws.html#potential-scale-reduction
-    .. [2] Gelman, Andrew, and Donald B. Rubin. (1992) “Inference from Iterative Simulation Using Multiple Sequences.” Statistical Science 7 (4): 457–72.
+    .. [StanRhat] https://mc-stan.org/docs/2_27/reference-manual/notation-for-samples-chains-and-draws.html#potential-scale-reduction
+    .. [Gelman1992] Gelman, Andrew, and Donald B. Rubin. (1992) “Inference from Iterative Simulation Using Multiple Sequences.” Statistical Science 7 (4): 457–72.
 
     """
     assert (
@@ -97,17 +97,17 @@ def effective_sample_size(
     where :math:`M` is the number of chains, :math:`N` the number of draws,
     :math:`\\hat{\\rho}_t` is the estimated _autocorrelation at lag :math:`t`, and
     :math:`K` is the last integer for which :math:`\\hat{P}_{K} = \\hat{\\rho}_{2K} +
-    \\hat{\\rho}_{2K+1}` is still positive.
+    \\hat{\\rho}_{2K+1}` is still positive [StanEff]_ [Gelman2013]_.
 
     The current implementation is similar to Stan, which uses Geyer's initial monotone sequence
-    criterion (Geyer, 1992; Geyer, 2011).
+    criterion [Geyer1992]_ [Geyer2011]_.
 
     References
     ----------
-    .. [1] https://mc-stan.org/docs/2_27/reference-manual/effective-sample-size-section.html
-    .. [2] Gelman, Andrew, J. B. Carlin, Hal S. Stern, David B. Dunson, Aki Vehtari, and Donald B. Rubin. (2013). Bayesian Data Analysis. Third Edition. Chapman; Hall/CRC.
-    .. [3] Geyer, Charles J. (1992). “Practical Markov Chain Monte Carlo.” Statistical Science, 473–83.
-    .. [4] Geyer, Charles J. (2011). “Introduction to Markov Chain Monte Carlo.” In Handbook of Markov Chain Monte Carlo, edited by Steve Brooks, Andrew Gelman, Galin L. Jones, and Xiao-Li Meng, 3–48. Chapman; Hall/CRC.
+    .. [StanEff] https://mc-stan.org/docs/2_27/reference-manual/effective-sample-size-section.html
+    .. [Gelman2013] Gelman, Andrew, J. B. Carlin, Hal S. Stern, David B. Dunson, Aki Vehtari, and Donald B. Rubin. (2013). Bayesian Data Analysis. Third Edition. Chapman; Hall/CRC.
+    .. [Geyer1992] Geyer, Charles J. (1992). “Practical Markov Chain Monte Carlo.” Statistical Science, 473–83.
+    .. [Geyer2011] Geyer, Charles J. (2011). “Introduction to Markov Chain Monte Carlo.” In Handbook of Markov Chain Monte Carlo, edited by Steve Brooks, Andrew Gelman, Galin L. Jones, and Xiao-Li Meng, 3–48. Chapman; Hall/CRC.
 
     """
     input_shape = input_array.shape

requirements-doc.txt

@@ -0,0 +1,7 @@
+-e ./
+jax
+jaxlib
+myst_nb
+sphinx
+sphinx-autobuild
+sphinx-book-theme