docs(backport): Use jupyterlite-sphinx to embed JupyterLite in docs (#…

…2205)

Backport components of:
   - PR #2187
   - PR #2190
   - PR #2192

.flake8

@@ -4,3 +4,6 @@
 # E501: line too long
 extend-ignore = E203, E402, E501
 max-line-length = 88
+
+per-file-ignores =
+    docs/lite/jupyterlite.py:F401,F704

.github/workflows/docs.yml

@@ -81,6 +81,8 @@ jobs:
         [ ! -L "docs/_build/html/schemas" ]
         # is not empty
         [ "$(ls -A docs/_build/html/schemas)" ]
+        # is not empty
+        [ "$(ls -A docs/_build/html/lite)" ]
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v1

docs/conf.py

@@ -15,12 +15,21 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use Path('../relative_path_to_dir').resolve() to make it absolute, like shown here.
 
-from pathlib import Path
 import sys
+from pathlib import Path
+
+import jupytext
 from pkg_resources import get_distribution
 
 sys.path.insert(0, str(Path('./exts').resolve()))
 
+# Convert jupyterlite example to ipynb
+docs_dir = Path(__file__).resolve().parent
+py_percent_as_notebook = jupytext.read(docs_dir / "lite" / "jupyterlite.py")
+jupytext.write(
+    py_percent_as_notebook, docs_dir / "lite" / "jupyterlite.ipynb", fmt="ipynb"
+)
+
 
 def setup(app):
     app.add_css_file(
@@ -52,8 +61,8 @@ def setup(app):
     'nbsphinx',
     'sphinx_issues',
     'sphinx_copybutton',
-    'sphinx_togglebutton',
     'xref',
+    'jupyterlite_sphinx',
 ]
 bibtex_bibfiles = [
     "bib/docs.bib",
@@ -177,6 +186,7 @@ def setup(app):
 exclude_patterns = [
     '_build',
     'JOSS',
+    'lite',
     '**.ipynb_checkpoints',
     'examples/experiments/edwardpyhf.ipynb',
     'examples/notebooks/ImpactPlot.ipynb',
@@ -510,3 +520,6 @@ def setup(app):
     r'https://pyhf.readthedocs.io/en/.*',
 ]
 linkcheck_retries = 50
+
+# JupyterLite configuration
+jupyterlite_dir = "lite"

docs/jupyterlite.rst

@@ -1,30 +1,14 @@
 Try out now with JupyterLite_
 -----------------------------
 
-.. admonition:: To try pyhf code in the browser with the Pyolite JupyterLite kernel:
-    :class: dropdown
-
-     #. Type (or copy and paste) code in the input cell.
-     #. To execute the code, press ``Shift + Enter`` or click on the (Run) ▶ button in the toolbar.
-
-     To get going try copying and pasting the "Hello World" example below!
-
-     .. admonition:: Kernel not loading?
-      :class: dropdown
-
-       If the kernel isn't loading and you just see a blank iframe, you will need your
-       browser to accept cookies from jupyterlite.github.io and then reload the page.
-
 ..
-  Comment: iframe below generated by docs/generate_jupyterlite_iframe.py
-
-.. raw:: html
+  Comment: Use https://github.com/jupyterlite/jupyterlite-sphinx
 
-   <iframe
-      src="https://jupyterlite.github.io/demo/repl/index.html?kernel=python&toolbar=1&code=import%20piplite%0Aawait%20piplite.install%28%5B%22pyhf%3D%3D0.7.1%22%2C%20%22matplotlib%3E%3D3.0.0%22%5D%29%0A%25matplotlib%20inline%0Aimport%20pyhf"
-      width="100%"
-      height="500px"
-   ></iframe>
+.. retrolite:: lite/jupyterlite.ipynb
+   :width: 100%
+   :height: 600px
+   :prompt: Try pyhf!
+   :prompt_color: #3a77b0
 
 ..
   Comment: Add an extra blank line as a spacer

docs/lite/jupyter-lite.json

@@ -0,0 +1,8 @@
+{
+  "jupyter-lite-schema-version": 0,
+  "jupyter-config-data": {
+    "enableMemoryStorage": true,
+    "settingsStorageDrivers": ["memoryStorageDriver"],
+    "contentsStorageDrivers": ["memoryStorageDriver"]
+  }
+}

docs/lite/jupyterlite.py

@@ -0,0 +1,27 @@
+# ---
+# jupyter:
+#   kernelspec:
+#     display_name: Python (Pyodide)
+#     language: python
+#     name: python
+# ---
+
+# %% [markdown]
+# # `pyhf` in the browser
+
+# %% [markdown]
+# * To run the code, click on the first cell (gray box) and press <kbd>Shift</kbd>+<kbd>Enter</kbd> or click on the (Run) ▶ button to run each cell.
+# * Alternatively, from the `Run` menu select `Run All Cells`.
+# * Feel free to experiment, and if you need to restore the original code reload this browser page. Any changes you make will be lost when you reload.
+#
+# To get going try copying and pasting the "Hello World" example below!
+
+# %%
+import piplite
+
+# Install pyhf in the browser
+await piplite.install(["pyhf==0.7.1", "matplotlib>=3.0.0"])
+# %matplotlib inline
+import pyhf
+
+# You can now use pyhf!

docs/lite/jupytext.toml

@@ -0,0 +1,3 @@
+# Always pair ipynb notebooks in the current directory to py:percent files
+formats = ["ipynb", "py:percent"]
+notebook_metadata_filter = "-all,kernelspec"

pyproject.toml

@@ -114,8 +114,10 @@ docs = [
     "nbsphinx!=0.8.8",  # c.f. https://github.com/spatialaudio/nbsphinx/issues/620
     "ipywidgets",
     "sphinx-issues",
-    "sphinx-copybutton>=0.3.2",
-    "sphinx-togglebutton>=0.3.0",
+    "sphinx-copybutton>=0.3.2,!=0.5.1",
+    "jupyterlite-sphinx>=0.8.0",
+    "jupyterlite-pyodide-kernel>=0.0.7",
+    "jupytext>=1.14.0",
     "ipython!=8.7.0",  # c.f. https://github.com/scikit-hep/pyhf/pull/2068
 ]
 develop = [

tbump.toml

@@ -55,10 +55,7 @@ src = "codemeta.json"
 src = "CITATION.cff"
 
 [[file]]
-src = "docs/generate_jupyterlite_iframe.py"
-
-[[file]]
-src = "docs/jupyterlite.rst"
+src = "docs/lite/jupyterlite.py"
 
 [[field]]
 # the name of the field