Ctrl+K

Using MyST-NB-Bokeh

Using MyST-NB-Bokeh#

MyST-NB-Bokeh provides one function that glues a Bokeh figure into the Notebook and provides hooks for MyST-NB to read the glued data and paste it into a Markdown cell.

Adding to Configuration#

To use this extension, you will need to install it into your environment and then modify your Sphinx configuration. How you do this depends on what interface to Sphinx you’re using.

Standard Sphinx Site#

If you are building a standard Sphinx site, then the myst_nb_bokeh extension should be added to your conf.py file:

extensions = [
    ...
    "myst_nb_bokeh",
    ...
]

Note that the three dots indicate other values that may be in your extensions list, you should not copy them.

JupyterBook#

If you’re building a JupyterBook, then you’ll need to modify your Sphinx configuration in your _config.yml file. In this case, you need to add a custom Sphinx extension:

sphinx:
  extra_extensions:
  - myst_nb_bokeh

Configuring MyST-NB-Bokeh#

MyST-NB-Bokeh has no configuration options 🎉

When the extension is added to your Sphinx configuration, it will set one MyST-NB-bokeh specific configuration values:

  1. nb_mime_priority_overrides: This configuration value determines the priority of the mimetypes in the cell output. This extension sets our custom JS+Bokeh MIME type to be the highest priority for HTML rendering.

Gluing and Pasting Bokeh Figures#

To glue and paste Bokeh figures in your Notebooks, you need to import one function from this package: glue_bokeh(). You do not need to run the show() or any other output_* (for example, output_notebook()) functions to be able to glue and paste Bokeh figures. The BokehJS library is automatically added to the page if necessary, whenever a Bokeh figure is pasted.

glue_bokeh() takes two mandatory and one optional argument, so it has the same arguments as the glue() function from MyST-NB:

  1. name: Mandatory, the name under which the Bokeh figure should be stored.

  2. variable: Mandatory, the Bokeh figure to glue into the output.

  3. display: Optional, default False. When True, the plot will be displayed in the output of the cell where gluing takes place. This is convenient to inspect the plot.

Once a Bokeh figure has been glued into the Notebook, you can use all the same pasting directive functionality as is available from MyST-NB. Note that you cannot paste Bokeh plots inline to the text, because of how the plot is displayed.

The example below shows how to glue and paste Bokeh figures.

from bokeh.plotting import figure
from myst_nb_bokeh import glue_bokeh

p = figure(width=300, height=300)
p.circle(list(range(1, 10)), list(range(10, 1, -1)));

# When display is False or omitted, the figure is not displayed in this cell's output
glue_bokeh("bokeh_plot", p)

Once the figure is glued into the output, you can paste it using the {glue:}, {glue:any}, and {glue:figure} directives. MyST has the triple-backtick and colon-fence ways of using directives; we’re using the colon-fence method in this document. The following Markdown will paste the bokeh_plot that we glued in the last cell:

We can also use the {glue:figure} directive to add a caption and cross-referencing. You can paste the same figure multiple times. Each version of the figure is completely independent of each other.

The caption for this figure goes here.#

The caption for this figure goes here.#

Contents