Sphinx Thebe

Common errors

• ModuleNotFoundError: No module named 'sphinx_thebe'

  cause The `sphinx-thebe` package has not been installed in your Python environment or is not accessible to your Sphinx build.
  fix Install the package using pip: `pip install sphinx-thebe`.

• Interactive code blocks do not appear or the 'Run' button doesn't work.

  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.
  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.

• Thebe cells always show 'Initializing...' but never connect or run code.

  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.
  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.

Warnings

• gotcha 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.
  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'`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Clearly communicate the source of the interactive kernels and any associated security considerations in your documentation.

Install

• pip install sphinx-thebe Install package

Imports

• 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.

Quickstart

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