API Reference#

This page documents the Sphinx-Marimo extension API.

Extension Setup#

sphinx_marimo.setup(app)#

Main setup function for the Sphinx extension.

Parameters:

app (sphinx.application.Sphinx) – Sphinx application instance

Returns:

Extension metadata dictionary

Return type:

dict

This function is called by Sphinx during initialization. It registers:

  • Configuration values

  • The marimo directive

  • Event handlers for building notebooks

  • Static CSS and JavaScript files

Configuration Values#

The following configuration values can be set in conf.py:

marimo_notebook_dir#

Directory containing Marimo notebook files (relative to source directory).

Type:

str

Default:

“notebooks”

marimo_build_dir#

Directory for build artifacts (relative to output directory).

Type:

str

Default:

“_build/marimo”

marimo_output_dir#

Directory for static files (relative to output directory).

Type:

str

Default:

“_static/marimo”

marimo_default_height#

Default height for embedded notebooks.

Type:

str

Default:

“600px”

marimo_default_width#

Default width for embedded notebooks.

Type:

str

Default:

“100%”

Directive#

.. marimo:: notebook_path#

Embed a Marimo notebook in the documentation.

Param notebook_path:

Path to the notebook file (relative to marimo_notebook_dir)

Type notebook_path:

str

Options:

:height: (string)#

Height of the embedded iframe (e.g., “700px”, “80vh”)

:width: (string)#

Width of the embedded iframe (e.g., “100%”, “800px”)

:class: (string)#

Additional CSS classes to apply to the container

:theme: (string)#

Theme for the notebook (“light”, “dark”, or “auto”)

Example:

.. marimo:: examples/my_notebook.py
   :height: 800px
   :width: 90%
   :theme: dark