run code in browser (#22727)

Example for running notebooks on our docs directly in the browser by connecting to a binder instance launched on demand.
If this seems useful we can extend this to other examples gradually.

Signed-off-by: Max Pumperla <max.pumperla@googlemail.com>

binder/README.md

@@ -0,0 +1,6 @@
+# Dependencies for mybinder.org
+
+To run notebook examples directly in the browser with binder, we need to set up the right dependencies,
+so that the launched notebook can import them right away.
+
+The `requirements.txt` file contains dependencies for (most) of the notebooks in our documentation.

binder/requirements.txt

@@ -0,0 +1,4 @@
+# Set up requirements needed to build a binder server to launch into.
+-r ../doc/requirements-doc.txt
+-r ../python/requirements.txt
+ray[rllib, serve, tune]

doc/requirements-doc.txt

@@ -46,6 +46,7 @@ sphinx-book-theme==0.1.7
 sphinx-external-toc==0.2.3
 sphinxcontrib.yt==0.2.2
 sphinx-sitemap==2.2.0
+sphinx-thebe==0.1.1
 
 # MyST
 myst-parser==0.15.2

doc/source/conf.py

@@ -38,6 +38,7 @@ extensions = [
     "sphinx.ext.doctest",
     "sphinx.ext.coverage",
     "sphinx_external_toc",
+    "sphinx_thebe",
 ]
 
 myst_enable_extensions = [
@@ -51,6 +52,13 @@ myst_enable_extensions = [
     "replacements",
 ]
 
+# Thebe configuration for launching notebook cells within the docs.
+thebe_config = {
+    "selector": "div.highlight",
+    "repository_url": "https://github.com/ray-project/ray",
+    "repository_branch": "master",
+}
+
 # Cache notebook outputs in _build/.jupyter_cache
 # To prevent notebook execution, set this to "off". To force re-execution, set this to "force".
 # To cache previous runs, set this to "cache".

doc/source/tune/examples/tune-sklearn.ipynb

@@ -78,6 +78,10 @@
     "``TuneGridSearchCV`` with a\n",
     "[SGDClassifier](https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.SGDClassifier.html).\n",
     "\n",
+    "\n",
+    "```{thebe-button} Activate code examples\n",
+    "```\n",
+    "\n",
     "To start out, change the import statement to get tune-scikit-learn’s grid search cross validation interface:"
    ]
   },