docs(backport): Update docs build requirements (#2281)

* Backport components of:
   - PR #2252
   - PR #2255
   - PR #2267
   - PR #2271
   - PR #2272
   - PR #2276

Author: matthewfeickert

.readthedocs.yaml

@@ -28,4 +28,3 @@ python:
       path: .
       extra_requirements:
         - docs
-  system_packages: true

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

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

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/.*',

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:
 

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",

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",