sphinx-thebe

library0.3.1pypypiunverified

Sphinx Thebe is a Sphinx extension that integrates interactive code blocks into documentation using Thebe.js and Binder. It allows readers to execute code examples directly in their browser against a live Jupyter kernel. The current version is 0.3.1, with releases occurring periodically to address Sphinx compatibility and feature enhancements.

web-framework

pip install sphinx-thebe

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINX-THEBE

sphinx-thebe

web-frameworkpythonv0.3.1

Install

5.2s avg

Import

—

Disk

94MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 92.1MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.2s · import 0.000s · 93MB

94MB installed

● package 94MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sphinx_thebe

✓ extensions = ['sphinx_thebe']

sphinx-thebe is a Sphinx extension; it is added to the `extensions` list in `conf.py` and not imported directly into Python source files.

To quickly get started, install the package, then add `sphinx_thebe` to your `conf.py` extensions list. Crucially, define a `thebe_config` dictionary specifying your BinderHub URL and kernel details. Finally, use the `thebe-button` directive followed by a code block in your reStructuredText or MyST Markdown files.

# 1. Install sphinx-thebe: # pip install sphinx-thebe # 2. In your Sphinx project's conf.py, add 'sphinx_thebe' to extensions: # extensions = [ # 'sphinx_thebe' # ] # 3. Configure thebe_config (replace with your BinderHub URL and kernel): # thebe_config = { # 'repository_url': 'https://github.com/binder-examples/jupyter-stacks-datascience', # 'repository_branch': 'master', # 'binderhub_url': 'https://mybinder.org', # 'kernel_name': 'python3', # 'code_selector': 'div.highlight', # 'always_load': false # } # 4. In a reStructuredText file (.rst) or MyST Markdown file (.md) write: # .. thebe-button:: # :label: Run this code! # .. code-block:: python # print('Hello, Thebe!') # x = 1 + 1 # print(f'x is {x}') # 5. Build your Sphinx documentation: # make html

Debug

Known issues

gotchaSphinx-thebe requires a configured BinderHub instance (e.g., mybinder.org) to fetch live kernels. If `binderhub_url` and `repository_url` are not correctly set in `thebe_config`, interactive cells will not function.

fix

Ensure `thebe_config` in `conf.py` has valid `binderhub_url` and `repository_url` pointing to a compatible Binder repository. For example: `binderhub_url: 'https://mybinder.org', repository_url: 'https://github.com/binder-examples/jupyter-stacks-datascience'`.

affects: All versions

gotchaBy default, Thebe.js is lazily loaded, meaning interactive buttons only appear and become active after an initial click. Users expecting immediate interactivity on page load might be confused.

fix

To force eager loading, set `'always_load': true` in your `thebe_config` dictionary in `conf.py`. Be aware this increases initial page load time.

affects: >=0.1.0

gotchaIf you are heavily customizing Thebe's frontend with custom JavaScript that directly manipulates its DOM elements or relies on specific jQuery versions, updates in `sphinx-thebe` (like the v0.3.1 jQuery fix) could cause unexpected behavior.

fix

Review custom frontend scripts after upgrading `sphinx-thebe` to ensure compatibility with updated internal dependencies. Test thoroughly, especially if you're injecting custom JavaScript into Thebe's components.

affects: >=0.3.1

gotchaInteractive code execution implies running arbitrary code from a remote source. Ensure users understand the security implications, especially if your BinderHub is self-hosted or allows user-defined environments.

fix

Clearly communicate the source of the interactive kernels and any associated security considerations in your documentation.

affects: All versions

Upgrade

Version history

0.3.1latest on PyPI · released Feb 7, 2024

Audit

Dependencies

sphinxrequiredThis is a Sphinx extension and requires Sphinx to build documentation.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/executablebooks/sphinx-thebe ↗

packagehttps://pypi.org/project/sphinx-thebe/ ↗