API Reference

MyST-NB-Bokeh enables gluing and pasting Bokeh plots when using the MyST-NB Sphinx extension.

class myst_nb_bokeh.BokehGlueDomain(env)

Bases: sphinx.domains.Domain

A Sphinx domain for handling Bokeh data.

Parameters

env (BuildEnvironment) –

Return type

None

data_version = 1

Data version, bump this when the format of self.data changes

has_bokeh(docname=None)

Return whether or not this page requires BokehJS.

Parameters

docname (Optional[str]) – The name of the document being processed.

Returns

Boolean whether or not the page requires BokehJS.

Return type

bool

initial_data: dict[str, dict[str, bool]] = {'has_bokeh': {}}

Data value for a fresh environment. has_bokeh is a mapping of docnames to a Boolean whether or not it has Bokeh

label = 'BokehGlue'

The label used for this domain

name = 'bokeh_glue'

The name of this domain

process_doc(env, docname, document)

Set internal data for whether or not this page requires BokehJS.

Parameters

  • env (BuildEnvironment) – The Sphinx build environment instance.

  • docname (str) – The name of the page being processed.

  • document (nodes.document) – The doctree of the current page.

Return type

None

class myst_nb_bokeh.BokehOutputRenderer(*args, **kwargs)

Bases: myst_nb.render_outputs.CellOutputRenderer

Render Bokeh JSON output from a cell’s output.

This class extends the CellOutputRenderer class to add a method that renders Bokeh JSON output into a <div> element in the page. We do this by adding a new key to the _render_map attribute of CellOutputRenderer. The key is the value of the JB_BOKEH_MIMETYPE module data member.

__init__(*args, **kwargs)

Initialize the BokehOutputRenderer.

Any positional or keyword arguments are passed to the superclass constructor. This class takes no additional arguments.

render_bokeh(output, index)

Output Sphinx nodes for Bokeh plots given the JSON of the plot.

Parameters

  • output (NotebookNode) – The output nodes from the cell. NotebookNode instances can be accessed like dictionaries.

  • index (int) – The cell index.

Returns

A list of docutils.nodes.Node instances. The two nodes returned here are the <div> that will contain the plot and a <script> with the appropriate BokehJS call to turn the JSON into a plot.

Return type

list[nodes.Node]

myst_nb_bokeh.JB_BOKEH_MIMETYPE: str = 'application/jupyter-book-bokeh-json'

The mimetype that we use for JSON output from Bokeh. This is a custom mimetype to avoid conflicting with any actual mimetypes.

myst_nb_bokeh.add_our_configuration(app, config)

Add the configuration for MyST-NB to the Sphinx configuration.

Designed to be connected to the 'config-inited' Sphinx event to ensure that all configuration sources have been read. The function signature is determined by the Sphinx API.

Parameters

  • app (Sphinx) – The Sphinx application instance.

  • config (Config) – The Sphinx configuration instance.

Return type

None

myst_nb_bokeh.glue_bokeh(name, variable, display=False)

Glue Bokeh figures into the cell output.

Parameters

  • name (str) – The name to give to the variable in the cell output. This name must be used when pasting this output in other cells.

  • variable (object) – The object to be inserted into the cell output. Note that the object itself is not stored. Rather, this function inserts the JSON representation of the plot into the cell output, which must then be extracted and shown by the BokehOutputRenderer.

  • display (bool) – If True, the plot will be shown in the output of the cell. Useful for sanity checking the output. False by default.

Return type

None

myst_nb_bokeh.install_bokeh(app, pagename, templatename, context, doctree)

Add BokehJS files to the page, if the page has Bokeh plots.

Designed to be connected to the 'html-page-context' Sphinx event. If the builder format is not an HTML file, this function does nothing. The function signature is determined by the Sphinx API.

Parameters

  • app (Sphinx) – The Sphinx application instance.

  • pagename (str) – The page being processed.

  • templatename (str) – The template in use.

  • context (dict) – The context dictionary for the template.

  • doctree (Optional[nodes.Node]) – The doctree being processed.

Return type

None

myst_nb_bokeh.setup(app)

Set up the MyST-NB-Bokeh Sphinx extension.

This function is automatically called by Sphinx, as long as this extension is listed in the list of extensions in your Sphinx conf.py file.

Parameters

app (Sphinx) – The Sphinx application, which is always passed by Sphinx during the initialization process.

Returns

A dictionary containing the version of this extension.

Return type

dict[str, str]