Add binder and thebe integration

docs/README.md

@@ -30,3 +30,93 @@ sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/p
 # build docs
 sphinx-build -n -W --keep-going -b html ./ ./_build/
 ```
+
+## Interactive notebooks
+
+### colab 
+- google product so requires users to have a google account
+- does not set up the env automatically so in your notebook include commands for installing dependencies e.g.
+    ```python
+    # for colab
+    !pip install python_package
+    ```
+
+#### Setup
+- configure launch_buttons in html_theme_options
+- for example:
+    ```python
+    html_theme_options = {
+        ...
+        "launch_buttons": {
+            ...
+            "colab_url": "https://colab.research.google.com",
+        }
+    ```
+
+### binder
+- doesn't require users to install things into env like colab does
+
+#### Setup
+- have repository_url and branch in html_theme_options of conf.py
+- also configure launch_buttons in html_theme_options
+    - [mybinder.org](https://jupyter.org/binder#binderhub) is a free service
+    - or [deploy your own?](https://jupyter.org/binder#binderhub)
+- for example:
+    ```python
+    html_theme_options = {
+        ...
+        "repository_url": "https://github.com/biosustain/python_package",
+        "repository_branch": "main",
+        "launch_buttons" : {
+            ...
+            "binderhub_url": "https://mybinder.org",
+            "notebook_interface": "jupyterlab",
+        }
+    }
+    ```
+
+
+### thebe
+- relies on binder
+- turns notebooks to interactive code cells in the docs in the browser. 
+
+#### Extra Requirements
+- installation of [`sphinx-thebe`](https://sphinx-thebe.readthedocs.io/en/latest/) e.g. add sphinx-thebe to docs group of [pyproject.toml](../pyproject.toml)
+- also add to `extensions` in sphinx conf.py
+
+#### Setup
+- configure thebe in html_theme_options in [conf.py](conf.py)
+    ```python
+    html_theme_options = {
+        ...
+       # for binder which is used by thebe
+        "repository_url": "https://github.com/biosustain/python_package",
+        "repository_branch": "main",
+        "launch_buttons" : {
+            ...
+            "thebe": True
+        }
+    }
+    ```
+    - instead can configure thebe repository url and branch in `thebe_config`
+- the `selector` in `thebe_config` tells thebe what html element to search for to tun into a runnable code cell 
+- if wanting to make all code cells runnable set `selector` to `<div>`s with `class="highlight`
+    ```python
+    # thebe options
+    thebe_config = {
+    "selector": "div.highlight",
+    "repository_url": "https://github.com/biosustain/python_package", # optional, will take from html_theme_options
+    "repository_branch": "main", # optional    
+    }
+    ``` 
+- by adding thebe to launch_buttons configuration, there will already be "▶️ Live Code" option from the launch button of the notebook-derived pages
+- you can also add an [html button to trigger thebe](https://sphinx-thebe.readthedocs.io/en/latest/configure.html#adding-your-own-button-to-start-thebe)
+    e.g. for sphinx-book-theme:
+    this code: 
+    ```markdown
+    <button class="thebe-button" onclick="initThebeSBT()">Activate Notebook</button>
+    ```
+    produces:
+    <button class="thebe-button" onclick="initThebeSBT()">Activate Notebook</button>
+
+

docs/conf.py

@@ -37,6 +37,7 @@
     "sphinx_new_tab_link",  # each link opens in a new tab
     "myst_nb",  # Markdown and Jupyter Notebook support
     "sphinx_copybutton",  # add copy button to code blocks
+    "sphinx_thebe",  # make code blocks executable in the browser using Thebe
 ]
 
 #  https://myst-nb.readthedocs.io/en/latest/computation/execute.html
@@ -86,6 +87,10 @@
     # "matplotlib": ("https://matplotlib.org/stable/", None),
 }
 
+# thebe options
+# https://sphinx-thebe.readthedocs.io
+thebe_config = {"selector": "div.highlight"}  # makes ALL code cells runnable
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -97,8 +102,8 @@
 # html_logo = "_static/logo-wide.svg"
 # html_favicon = "_static/logo-square.svg"
 html_theme_options = {
-    "github_url": "https://github.com/RasmussenLab/python_package",
-    "repository_url": "https://github.com/RasmussenLab/python_package",
+    "github_url": "https://github.com/biosustain/python_package",
+    "repository_url": "https://github.com/biosustain/python_package",
     "repository_branch": "main",
     "home_page_in_toc": True,
     "path_to_docs": "docs",
@@ -107,9 +112,10 @@
     "use_repository_button": True,
     "use_download_button": True,
     "launch_buttons": {
-        "colab_url": "https://colab.research.google.com"
-        #     "binderhub_url": "https://mybinder.org",
-        #     "notebook_interface": "jupyterlab",
+        "colab_url": "https://colab.research.google.com",
+        "binderhub_url": "https://mybinder.org",
+        "notebook_interface": "jupyterlab",
+        "thebe": True,
     },
     "navigation_with_keys": False,
 }

docs/tutorial/tutorial.ipynb

@@ -8,7 +8,9 @@
     "# Python Package tutorial\n",
     "\n",
     "Run when documentation is build. Building documentation therefore can become\n",
-    "an minimal integration test for the package."
+    "an minimal integration test for the package.\n",
+    "\n",
+    "<button class=\"thebe-button\" onclick=\"initThebeSBT()\">Activate Notebook</button>"
    ]
   },
   {
@@ -94,6 +96,9 @@
    "cell_metadata_filter": "-all",
    "main_language": "python",
    "notebook_metadata_filter": "-all"
+  },
+  "language_info": {
+   "name": "python"
   }
  },
  "nbformat": 4,

docs/tutorial/tutorial.py

@@ -3,6 +3,8 @@
 #
 # Run when documentation is build. Building documentation therefore can become
 # an minimal integration test for the package.
+#
+# <button class="thebe-button" onclick="initThebeSBT()">Activate Notebook</button>
 
 # %%
 from python_package import hello_world

pyproject.toml

@@ -42,6 +42,7 @@ docs = [
   "sphinx-new-tab-link!=0.2.2",
   "jupytext",
   "sphinx-copybutton",
+  "sphinx-thebe"
 ]
 # local development options
 dev = ["black[jupyter]", "ruff", "pytest", "isort", "jupytext"]