Run Code In The Docs#

This project enables running Python examples directly in the documentation using Thebe + Binder.

How it works#

  • The documentation includes Thebe (a small JS client) which can request a live Jupyter kernel from Binder.

  • When you open a page with a code block, click the run button that appears to execute the cell in a live kernel and see outputs inline.

Binder environment#

  • A minimal Binder environment is provided at binder/requirements.txt for lightweight examples.

  • Heavy libraries (PyTorch) are intentionally not included by default because they make Binder builds very slow and often fail due to size limits. If you need PyTorch in Binder, create a custom Binder environment with CPU-only wheels and update the thebe_config accordingly.

Usage notes & caveats#

  1. Click the run/play button in the top-right of a code block to run it.

  2. First-run may take time while Binder spins up a server (a few tens of seconds to minutes).

  3. Sessions are temporary. Save work to your local machine if needed.

Security#

Running code on Binder executes on remote compute provided by Binder. Be cautious with secrets or downloading large datasets.

Customization#

To point Thebe at a different Binder repo/branch, edit thebe_config in docs/source/conf.py and rebuild the docs.