From f97b885405b7ee2ea0fab9679ff2e6e0cbe438db Mon Sep 17 00:00:00 2001
From: Matthew Feickert <matthew.feickert@cern.ch>
Date: Wed, 16 Aug 2023 04:09:06 -0500
Subject: [PATCH] docs(backport): Update docs build requirements (#2281)

* Backport components of:
   - PR https://github.com/scikit-hep/pyhf/pull/2252
   - PR https://github.com/scikit-hep/pyhf/pull/2255
   - PR https://github.com/scikit-hep/pyhf/pull/2267
   - PR https://github.com/scikit-hep/pyhf/pull/2271
   - PR https://github.com/scikit-hep/pyhf/pull/2272
   - PR https://github.com/scikit-hep/pyhf/pull/2276
---
 .readthedocs.yaml                                           | 1 -
 README.rst                                                  | 2 +-
 binder/postBuild                                            | 5 ++++-
 docs/conf.py                                                | 6 ++++++
 docs/examples.rst                                           | 2 +-
 .../notebooks/binderexample/StatisticalAnalysis.ipynb       | 4 ++--
 pyproject.toml                                              | 5 +++--
 7 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 7c786083a9..bdab4e8207 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -28,4 +28,3 @@ python:
       path: .
       extra_requirements:
         - docs
-  system_packages: true
diff --git a/README.rst b/README.rst
index 14d38d62aa..a5c44e75e9 100644
--- a/README.rst
+++ b/README.rst
@@ -372,7 +372,7 @@ and grant `OAC-1450377 <https://www.nsf.gov/awardsearch/showAward?AWD_ID=1450377
 .. |Jupyter Book tutorial| image:: https://jupyterbook.org/_images/badge.svg
    :target: https://pyhf.github.io/pyhf-tutorial/
 .. |Binder| image:: https://mybinder.org/badge_logo.svg
-   :target: https://mybinder.org/v2/gh/scikit-hep/pyhf/main?filepath=docs%2Fexamples%2Fnotebooks%2Fbinderexample%2FStatisticalAnalysis.ipynb
+   :target: https://mybinder.org/v2/gh/scikit-hep/pyhf/main?labpath=docs%2Fexamples%2Fnotebooks%2Fbinderexample%2FStatisticalAnalysis.ipynb
 
 .. |PyPI version| image:: https://badge.fury.io/py/pyhf.svg
    :target: https://badge.fury.io/py/pyhf
diff --git a/binder/postBuild b/binder/postBuild
index c7af738a91..6df0538e05 100644
--- a/binder/postBuild
+++ b/binder/postBuild
@@ -1,2 +1,5 @@
 python -m pip install --upgrade '.[all]'
-python -m pip install altair
+python -m pip install --upgrade \
+    ipywidgets \
+    ipympl \
+    altair
diff --git a/docs/conf.py b/docs/conf.py
index cda874ee89..062f1f5eb7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -515,6 +515,12 @@ def setup(app):
     r'https://doi\.org/10\.31526/.*',
     # https://doi.org/10.1051/epjconf/x DOI URLs will periodically generate 500 Server Error
     r'https://doi\.org/10\.1051/epjconf/.*',
+    # https://indico.desy.de/event/22731/contributions/47953/ is frequently generating 403 Client Error
+    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/.*',
+    # 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
     # and ReadTheDocs need to reference them
     r'https://github.com/scikit-hep/pyhf/releases/tag/.*',
diff --git a/docs/examples.rst b/docs/examples.rst
index 8a9cfa19e8..255cf18d41 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -4,7 +4,7 @@ Examples
 Try out in Binder! |Binder|
 
 .. |Binder| image:: https://mybinder.org/badge_logo.svg
-    :target: https://mybinder.org/v2/gh/scikit-hep/pyhf/main?filepath=docs%2Fexamples%2Fnotebooks%2Fbinderexample%2FStatisticalAnalysis.ipynb
+    :target: https://mybinder.org/v2/gh/scikit-hep/pyhf/main?labpath=docs%2Fexamples%2Fnotebooks%2Fbinderexample%2FStatisticalAnalysis.ipynb
 
 Notebooks:
 
diff --git a/docs/examples/notebooks/binderexample/StatisticalAnalysis.ipynb b/docs/examples/notebooks/binderexample/StatisticalAnalysis.ipynb
index 42c3b4656d..8385164ba9 100644
--- a/docs/examples/notebooks/binderexample/StatisticalAnalysis.ipynb
+++ b/docs/examples/notebooks/binderexample/StatisticalAnalysis.ipynb
@@ -16,7 +16,7 @@
     "from pyhf.contrib.viz import brazil\n",
     "\n",
     "import base64\n",
-    "from IPython.core.display import display, HTML\n",
+    "from IPython.display import display, HTML\n",
     "from ipywidgets import interact, fixed"
    ]
   },
@@ -1248,7 +1248,7 @@
     }
    ],
    "source": [
-    "%matplotlib notebook\n",
+    "%matplotlib widget\n",
     "fig, ax = plt.subplots(1, 1)\n",
     "fig.set_size_inches(10, 5)\n",
     "ax.set_ylim(0, 1.5 * np.max(workspace.data(pdf, include_auxdata=False)))\n",
diff --git a/pyproject.toml b/pyproject.toml
index b16fdb1440..6a40b1dccc 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -98,6 +98,7 @@ test = [
     "pytest-benchmark[histogram]",
     "pytest-console-scripts>=1.4.0",
     "pytest-mpl",
+    "ipympl>=0.3.0",
     "pydocstyle",
     "papermill~=2.3.4",
     "scrapbook~=0.5.0",
@@ -107,10 +108,10 @@ test = [
 ]
 docs = [
     "pyhf[xmlio,contrib]",
-    "sphinx>=5.1.1",  # c.f. https://github.com/scikit-hep/pyhf/pull/1926
+    "sphinx>=7.0.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2271
     "sphinxcontrib-bibtex~=2.1",
     "sphinx-click",
-    "sphinx_rtd_theme",
+    "sphinx-rtd-theme>=1.3.0rc1",  # 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",