sphinx_gallery.interactive_example

Binder and Jupyterlite utility functions.

Integration with Binder and Jupyterlite is on an experimental stage. Note that this API may change in the future.

Warning

Binder is still beta technology, so there may be instability in the experience of users who click Binder links.

Functions

sphinx_gallery.interactive_example.check_binder_conf(binder_conf: dict[str, Any] | None) → dict[str, Any]

Check to make sure that the Binder configuration is correct.

sphinx_gallery.interactive_example.check_jupyterlite_conf(jupyterlite_conf: dict[str, Any] | None, app: Sphinx | None) → dict[str, Any] | None

Return full JupyterLite configuration with defaults.

sphinx_gallery.interactive_example.copy_binder_files(app: Sphinx, exception: Exception | None) → None

Copy all Binder requirements and notebooks files.

sphinx_gallery.interactive_example.create_jupyterlite_contents(app: Sphinx, exception: Exception | None) → None

Create Jupyterlite contents according to “jupyterlite” configuration.

sphinx_gallery.interactive_example.gen_binder_rst(fpath: str | os.PathLike, binder_conf: dict[str, Any], gallery_conf: GalleryConfig) → str

Generate the reST + link for the Binder badge.

Parameters:

• fpath (str) – The path to the .py file for which a Binder badge will be generated.

• binder_conf (dict) –

  A dictionary with the following keys:

  ’binderhub_url’

  The URL of the BinderHub instance that’s running a Binder service.

  ’org’

  The GitHub organization to which the documentation will be pushed.

  ’repo’

  The GitHub repository to which the documentation will be pushed.

  ’branch’

  The Git branch on which the documentation exists (e.g., gh-pages).

  ’dependencies’

  A list of paths to dependency files that match the Binderspec.

• gallery_conf (dict) – Sphinx-Gallery configuration dictionary.

Returns:

rst – The reStructuredText for the Binder badge that links to this file.

Return type:

str

sphinx_gallery.interactive_example.gen_binder_url(fpath: str | os.PathLike, binder_conf: dict[str, Any], gallery_conf: GalleryConfig) → str

Generate a Binder URL according to the configuration in conf.py.

Parameters:

• fpath (str) – The path to the .py file for which a Binder badge will be generated.

• binder_conf (dict) – The Binder configuration dictionary. See gen_binder_rst for details.

Returns:

binder_url – A URL that can be used to direct the user to the live Binder environment.

Return type:

str

sphinx_gallery.interactive_example.gen_jupyterlite_rst(fpath: str | os.PathLike, gallery_conf: GalleryConfig) → str

Generate the reST + link for the Binder badge.

Parameters:

• fpath (str | os.PathLike) – The path to the .py file for which a JupyterLite badge will be generated.

• gallery_conf (dict) – Sphinx-Gallery configuration dictionary.

Returns:

rst – The reStructuredText for the JupyterLite badge that links to this file.

Return type:

str

sphinx_gallery.interactive_example.post_configure_jupyterlite_sphinx(app: Sphinx, config: Config) → None

Check SG “jupyterlite” and update Jupyterlite config “jupyterlite_contents”.

Connected to “config-inited” event but lower priority so called after pre_configure_jupyterlite_sphinx.

sphinx_gallery.interactive_example.pre_configure_jupyterlite_sphinx(app: Sphinx, config: Config) → None

Configure ‘jupyterlite_bind_ipynb_suffix’ if jupyterlite enabled.

Connected to “config-inited” event.