Add interactive playground for users to try rustworkx

.gitignore

@@ -25,3 +25,5 @@ rustworkx-core/Cargo.lock
 **/.DS_Store
 venv/
 .python-version
+.jupyterlite.doit.db
+docs/source/.cache

docs/source/conf.py

@@ -14,7 +14,7 @@
 # rustworkx documentation build configuration file
 #
 
-import sys, os
+import sys, os, json, pathlib
 import subprocess
 
 # General configuration:
@@ -41,6 +41,7 @@
               'sphinxemoji.sphinxemoji',
               'sphinx_reredirects',
               'qiskit_sphinx_theme',
+              'jupyterlite_sphinx',
              ]
 templates_path = ['_templates']
 extra_css_files = ["overrides.css"]
@@ -111,6 +112,18 @@
 # Jupyter Sphinx options
 jupyter_execute_default_kernel = "python3"
 
+# JupyterLite Sphinx options for the Playground
+jupyterlite_config = "jupyter_lite_config.json"
+with open(jupyterlite_config, "r") as test_json_config:
+    # If there are syntax errors, jupyterlite fails silently
+    # so we validate with Python
+    test_config_dictionary = json.load(test_json_config)
+    playground_url = test_config_dictionary["PipliteAddon"]["piplite_urls"][0]
+    playground_wheel = pathlib.Path(__file__).parent / playground_url
+    # If the wheel does not exist, jupyterlite fails silently. So we check
+    # ourselves.
+    assert playground_wheel.is_file()
+
 # Texinfo options
 
 texinfo_documents = [

docs/source/index.rst

@@ -73,6 +73,7 @@ Contents:
 
    About Rustworkx <self>
    Installation and Getting Started <install>
+   Rustworkx Playground <playground>
    Rustworkx Tutorials and Guides <tutorial/index>
    Rustworkx API <api/index>
    Visualization <visualization>

docs/source/jupyter_lite_config.json

@@ -0,0 +1,10 @@
+{
+  "LiteBuildConfig": {
+    "no_sourcemaps": true,
+    "no_unused_shared_packages": true,
+    "apps": ["repl"]
+  },
+  "PipliteAddon": {
+    "piplite_urls": ["rustworkx-0.17.0-cp39-abi3-pyodide_2024_0_wasm32.whl"]
+  }
+}

docs/source/playground.rst

@@ -0,0 +1,28 @@
+.. _rustworkx_playground:
+
+####################
+Rustworkx Playground
+####################
+
+Welcome to the Rustworkx Playground! This is an interactive environment where you can
+experiment with Rustworkx on your browser.
+
+.. replite::
+   :kernel: python
+   :height: 600px
+   :prompt: Try it!
+   :prompt_color: #6929c4
+
+   import piplite
+   await piplite.install("rustworkx")
+
+   import rustworkx as rx
+   print(f"Rustworkx Playground with version: {rx.__version__}")
+
+.. note::
+   The `rustworkx` version in the playground is not always the latest. Verify the deployed
+   version with `rustworkx.__version__`.
+
+.. note::
+   The `rustworkx` version in the playground experimental. If you find any issues, please
+   report them at https://github.com/Qiskit/rustworkx/issues.

pyproject.toml

@@ -98,6 +98,12 @@ docs = [
     "sphinxemoji",
     "ipykernel",
     "lxml_html_clean",
+    # Required to pin Pyodide 0.27.6 with jupyterlite-sphinx.
+    # jupyterlite-pyodide-kernel is pinned to specific Pyodide versions,
+    # therefore we need to pick releases that are compatible.
+    "jupyterlite-sphinx==0.20.2",
+    "jupyterlite-core==0.6.0",
+    "jupyterlite-pyodide-kernel==0.6.0",
 ]
 releaseinfra = [
     "cibuildwheel==2.23.2",