From 436b3dff7c3f482073a5def4223753e47262d741 Mon Sep 17 00:00:00 2001
From: Matthew Feickert <matthew.feickert@cern.ch>
Date: Wed, 6 Sep 2023 15:37:44 -0500
Subject: [PATCH] docs(backport): Update docs requirements and use citations

* Backport:
   - PR https://github.com/scikit-hep/pyhf/pull/ 2291
   - PR https://github.com/scikit-hep/pyhf/pull/ 2300
   - PR https://github.com/scikit-hep/pyhf/pull/ 2306
   - PR https://github.com/scikit-hep/pyhf/pull/ 2308
   - PR https://github.com/scikit-hep/pyhf/pull/ 2309
   - PR https://github.com/scikit-hep/pyhf/pull/ 2312
   - PR https://github.com/scikit-hep/pyhf/pull/ 2315
   - PR https://github.com/scikit-hep/pyhf/pull/ 2316
---
 docs/bib/general_citations.bib | 12 ++++++++++++
 docs/bib/use_citations.bib     | 21 +++++++++++++++++++++
 docs/conf.py                   |  5 ++++-
 pyproject.toml                 |  2 +-
 4 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/docs/bib/general_citations.bib b/docs/bib/general_citations.bib
index 333fd221f2..d996d587b6 100644
--- a/docs/bib/general_citations.bib
+++ b/docs/bib/general_citations.bib
@@ -1,3 +1,15 @@
+% 2023-08-31
+@article{Kagan:2023gxz,
+    author = "Kagan, Michael and Heinrich, Lukas",
+    title = "{Branches of a Tree: Taking Derivatives of Programs with Discrete and Branching Randomness in High Energy Physics}",
+    eprint = "2308.16680",
+    archivePrefix = "arXiv",
+    primaryClass = "stat.ML",
+    month = "8",
+    year = "2023",
+    journal = ""
+}
+
 % 2023-06-06
 @article{Eschle:2023ikn,
     author = "Eschle, J. and others",
diff --git a/docs/bib/use_citations.bib b/docs/bib/use_citations.bib
index 6b8280e769..a99aab9cb4 100644
--- a/docs/bib/use_citations.bib
+++ b/docs/bib/use_citations.bib
@@ -1,3 +1,24 @@
+% 2023-09-04
+@article{Fenton:2023ikr,
+    author = "Fenton, Michael James and Shmakov, Alexander and Okawa, Hideki and Li, Yuji and Hsiao, Ko-Yang and Hsu, Shih-Chieh and Whiteson, Daniel and Baldi, Pierre",
+    title = "{Extended Symmetry Preserving Attention Networks for LHC Analysis}",
+    eprint = "2309.01886",
+    archivePrefix = "arXiv",
+    primaryClass = "hep-ex",
+    month = "9",
+    year = "2023",
+    journal = ""
+}
+
+% 2023-08-18
+@booklet{ATLAS-CONF-2023-040,
+    author = "{ATLAS Collaboration}",
+    title = "{Search for short- and long-lived axion-like particles in $H\rightarrow a a \rightarrow 4\gamma$ decays with the ATLAS experiment at the LHC}",
+    howpublished = "{ATLAS-CONF-2023-040}",
+    url = "https://cds.cern.ch/record/2867933",
+    year = "2023"
+}
+
 % 2023-07-18
 @article{Darme:2023nsy,
     author = "Darm\'e, Luc and Deandrea, Aldo and Mahmoudi, Farvah",
diff --git a/docs/conf.py b/docs/conf.py
index 062f1f5eb7..06ead2b2a7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -519,6 +519,8 @@ def setup(app):
     r'https://indico.desy.de/event/22731/.*',
     # https://indico.belle2.org/event/8470/contributions/55871/ is frequently generating 403 Client Error
     r'https://indico.belle2.org/event/8470/.*',
+    # https://doi.org/10.1142/S0217732321020016 is frequently generating 403 Client Error
+    r'https://doi\.org/10.1142/.*',
     # CERN doesn't maintain its SSL certs well enough to not have SSLErrors
     r'https://twiki.cern.ch/.*',
     # tags for a release won't exist until it is made, but the release notes
@@ -529,4 +531,5 @@ def setup(app):
 linkcheck_retries = 50
 
 # JupyterLite configuration
-jupyterlite_dir = "lite"
+# Use Path as jupyterlite-sphinx expects PosixPath
+jupyterlite_dir = Path("lite")
diff --git a/pyproject.toml b/pyproject.toml
index b1c04c8923..5468bc8847 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -111,7 +111,7 @@ docs = [
     "sphinx>=7.0.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
     "sphinxcontrib-bibtex~=2.1",
     "sphinx-click",
-    "sphinx-rtd-theme>=1.3.0rc1",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
+    "sphinx-rtd-theme>=1.3.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
     "nbsphinx!=0.8.8",  # c.f. https://github.com/spatialaudio/nbsphinx/issues/620
     "ipywidgets",
     "sphinx-issues",