From 3845635fc059a74f5742b96898692580fe750172 Mon Sep 17 00:00:00 2001
From: Adrien Corenflos <adrien.corenflos@gmail.com>
Date: Sat, 2 Dec 2023 12:58:20 +0200
Subject: [PATCH] Documenting Barker's proposal (#600)

---
 Makefile                |  2 +-
 blackjax/mcmc/barker.py |  3 ++-
 docs/refs.bib           | 15 +++++++++++++++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 6c1799e05..0c087df82 100644
--- a/Makefile
+++ b/Makefile
@@ -12,4 +12,4 @@ release:
 
 build-docs:
 	pip install -r requirements-doc.txt
-	sphinx-build -b html docs docs/_build/html
+	PYDEVD_DISABLE_FILE_VALIDATION=1 sphinx-build -b html docs docs/_build/html
diff --git a/blackjax/mcmc/barker.py b/blackjax/mcmc/barker.py
index f2095853d..cf698c7ea 100644
--- a/blackjax/mcmc/barker.py
+++ b/blackjax/mcmc/barker.py
@@ -131,7 +131,8 @@ def kernel(
 
 
 class barker_proposal:
-    """Implements the (basic) user interface for the Barker's proposal kernel with a Gaussian base kernel.
+    """Implements the (basic) user interface for the Barker's proposal :cite:p:`Livingstone2022Barker` kernel with a
+    Gaussian base kernel.
 
     The general Barker kernel builder (:meth:`blackjax.mcmc.barker.build_kernel`, alias `blackjax.barker.build_kernel`) can be
     cumbersome to manipulate. Since most users only need to specify the kernel
diff --git a/docs/refs.bib b/docs/refs.bib
index 1b6485809..0b7ff4e8c 100644
--- a/docs/refs.bib
+++ b/docs/refs.bib
@@ -378,3 +378,18 @@ @misc{robnik2023microcanonical
       archivePrefix={arXiv},
       primaryClass={stat.CO}
 }
+
+@article{Livingstone2022Barker,
+    author = {Livingstone, Samuel and Zanella, Giacomo},
+    title = "{The Barker Proposal: Combining Robustness and Efficiency in Gradient-Based MCMC}",
+    journal = {Journal of the Royal Statistical Society Series B: Statistical Methodology},
+    volume = {84},
+    number = {2},
+    pages = {496-523},
+    year = {2022},
+    month = {01},
+    issn = {1369-7412},
+    doi = {10.1111/rssb.12482},
+    url = {https://doi.org/10.1111/rssb.12482},
+    eprint = {https://academic.oup.com/jrsssb/article-pdf/84/2/496/49322274/jrsssb\_84\_2\_496.pdf},
+}