{"id":9323,"library":"sphinx-thebe","title":"Sphinx Thebe","description":"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.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-thebe","tags":["sphinx","documentation","interactive","jupyter","thebe","binder","education","code execution"],"install":[{"cmd":"pip install sphinx-thebe","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to build documentation.","package":"sphinx","optional":false}],"imports":[{"note":"sphinx-thebe is a Sphinx extension; it is added to the `extensions` list in `conf.py` and not imported directly into Python source files.","symbol":"sphinx_thebe","correct":"extensions = ['sphinx_thebe']"}],"quickstart":{"code":"# 1. Install sphinx-thebe:\n# pip install sphinx-thebe\n\n# 2. In your Sphinx project's conf.py, add 'sphinx_thebe' to extensions:\n# extensions = [\n#     'sphinx_thebe'\n# ]\n\n# 3. Configure thebe_config (replace with your BinderHub URL and kernel):\n# thebe_config = {\n#     'repository_url': 'https://github.com/binder-examples/jupyter-stacks-datascience',\n#     'repository_branch': 'master',\n#     'binderhub_url': 'https://mybinder.org',\n#     'kernel_name': 'python3',\n#     'code_selector': 'div.highlight',\n#     'always_load': false\n# }\n\n# 4. In a reStructuredText file (.rst) or MyST Markdown file (.md) write:\n# .. thebe-button::\n#    :label: Run this code!\n\n# .. code-block:: python\n\n#    print('Hello, Thebe!')\n#    x = 1 + 1\n#    print(f'x is {x}')\n\n# 5. Build your Sphinx documentation:\n# make html\n","lang":"python","description":"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."},"warnings":[{"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'`.","message":"Sphinx-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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"By 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":">=0.3.1"},{"fix":"Clearly communicate the source of the interactive kernels and any associated security considerations in your documentation.","message":"Interactive 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install sphinx-thebe`.","cause":"The `sphinx-thebe` package has not been installed in your Python environment or is not accessible to your Sphinx build.","error":"ModuleNotFoundError: No module named 'sphinx_thebe'"},{"fix":"1. Ensure a `.. thebe-button::` directive (or equivalent for MyST) precedes your code block. 2. Verify `thebe_config` in `conf.py` is correctly defined and points to valid resources (e.g., `binderhub_url`, `repository_url`). 3. Check your browser's developer console for network errors or JavaScript issues. 4. Confirm your Binder repository and specified kernel are functioning correctly.","cause":"This can be due to several reasons: missing `thebe-button` directive, incorrect `thebe_config` in `conf.py`, network issues preventing connection to BinderHub, or a misconfigured kernel.","error":"Interactive code blocks do not appear or the 'Run' button doesn't work."},{"fix":"Double-check the `binderhub_url` in your `thebe_config` in `conf.py`. Try accessing the BinderHub directly in your browser. Ensure there are no network restrictions (e.g., corporate firewalls) preventing your browser from connecting to the BinderHub URL. Review the BinderHub logs if you are hosting it yourself.","cause":"This typically indicates a problem with the connection to the BinderHub, either due to an incorrect URL, a blocked connection, or an issue with the Binder instance itself.","error":"Thebe cells always show 'Initializing...' but never connect or run code."}]}