sphinx-marimo
A Sphinx extension for embedding interactive Marimo notebooks in documentation with WASM support, similar to Jupyter-Lite.
Installation
Using uv (recommended):
uv add sphinx-marimo
Or using pip:
pip install sphinx-marimo
Quick Start
- Add the extension to your
conf.py:
extensions = [
'sphinx_marimo',
# ... other extensions
]
# Optional configuration
marimo_notebook_dir = 'notebooks' # Directory containing .py Marimo notebooks
marimo_default_height = '600px'
marimo_default_width = '100%'
- Create a Marimo notebook (
.pyfile):
import marimo
__generated_with = "0.1.0"
app = marimo.App()
@app.cell
def __():
import marimo as mo
return mo,
@app.cell
def __(mo):
slider = mo.ui.slider(1, 10, value=5)
mo.md(f"Value: {slider.value}")
return slider,
- Embed it in your documentation:
.. marimo:: path/to/notebook.py
:height: 800px
:width: 100%
Click-to-Load Feature
Marimo notebooks use WASM which can be compute-intensive. The extension offers multiple loading modes to optimize performance and user experience:
Loading Modes
# In conf.py
marimo_click_to_load = True # Can be: False, True/"overlay", or "compact"
marimo_load_button_text = "Load Interactive Notebook" # Customize button text
Available Modes:
- Immediate Loading (
False) - Traditional behavior, notebooks load immediately - Overlay Mode (
Trueor"overlay") - Full-height overlay with centered button (default) - Compact Mode (
"compact") - Space-saving button that expands when clicked
Per-Notebook Configuration
Override the global setting for individual notebooks:
# Compact mode - saves screen space
.. marimo:: heavy_computation.py
:click-to-load: compact
:load-button-text: Run Analysis
# Overlay mode - full height with centered button
.. marimo:: demo.py
:click-to-load: overlay
:load-button-text: Start Demo
# Immediate loading - no button
.. marimo:: quick_example.py
:click-to-load: false
Use Cases:
- Compact mode: Perfect for documentation with multiple notebooks on one page
- Overlay mode: Best for standalone demos where the notebook is the focus
- Immediate loading: Ideal for lightweight, essential notebooks
This flexibility allows you to optimize for:
- Better page load times on mobile devices
- Reduced bandwidth for users who don't interact with every notebook
- Improved user experience with progressive disclosure
Architecture
The extension works by:
- Build Phase: Converting Marimo
.pynotebooks to WASM during Sphinx build - Runtime: Serving notebooks as static files that run in the browser
- Click-to-Load: Deferring notebook loading until user interaction for better performance
Examples
See the documentation for live examples and full usage guide.
Requirements
- Python 3.8+
- Sphinx 4.0+
- Marimo 0.1.0+
Metadata
Release files for sphinx-marimo 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sphinx_marimo-0.3.0.tar.gz | 271.8 kB | Without provenance | Details for sphinx_marimo-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sphinx_marimo-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for sphinx_marimo-0.3.0-py3-none-any.whl |
Total release size: 287.7 kB
Release files / sphinx_marimo-0.3.0.tar.gz
| Download URL | sphinx_marimo-0.3.0.tar.gz |
|---|---|
| Size | 271.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e27883a673868b53140789b31674bc19c59a8122e9eea0267ca6c15fd9f72f17
|
|
BLAKE2b-256 checksum How to use checksums |
daa2d6c6c025da4813ea3f736a089a052ff2c6d4ab727abf8331ed4e80b062e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / sphinx_marimo-0.3.0-py3-none-any.whl
| Download URL | sphinx_marimo-0.3.0-py3-none-any.whl |
|---|---|
| Size | 15.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
205fca3aed0607d480fa9c3baafdd038fc85b899077793b04444beaa30356122
|
|
BLAKE2b-256 checksum How to use checksums |
979cd2141e67a51256c80f2f1879602c010e9a0f6002913edfd3012e8e112891
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for sphinx-marimo 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.