{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Using MyST-NB-Bokeh\n", "\n", "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.\n", "\n", "\n", "## Adding to Configuration\n", "\n", "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.\n", "\n", "### Standard Sphinx Site\n", "\n", "If you are building a standard Sphinx site, then the `myst_nb_bokeh` extension should be added to your `conf.py` file:\n", "\n", "```python\n", "extensions = [\n", " ...\n", " \"myst_nb_bokeh\",\n", " ...\n", "]\n", "```\n", "\n", "Note that the three dots indicate other values that may be in your `extensions` list, you should not copy them.\n", "\n", "### JupyterBook\n", "\n", "If you're building a [JupyterBook](https://jupyterbook.org), 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](https://jupyterbook.org/advanced/sphinx.html#custom-sphinx-extensions):\n", "\n", "```yaml\n", "sphinx:\n", " extra_extensions:\n", " - myst_nb_bokeh\n", "```\n", "\n", "### Configuring MyST-NB-Bokeh\n", "\n", "MyST-NB-Bokeh has no configuration options 🎉\n", "\n", "When the extension is added to your Sphinx configuration, it will set two MyST-NB specific configuration values:\n", "\n", "1. **`nb_render_priority`**: This configuration value determines the priority of the [mimetypes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the cell output. If the value is set when MyST-NB-Bokeh is loaded, the extension shows a warning and attempts to modify the list to add its configuration value.\n", "2. **`nb_render_plugin`**: This configuration value determines what plugin should be used to render the cell outputs. MyST-NB-Bokeh provides a plugin that extends the default set of renderers with one to handle Bokeh figures. If this value is set to something other than `\"default\"` or `\"bokeh\"` when MyST-NB-Bokeh is loaded, a warning is shown and the value is not changed.\n", "\n", "## Gluing and Pasting Bokeh Figures\n", "\n", "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.\n", "\n", "`glue_bokeh()` takes two mandatory and one optional argument, so it has the same arguments as the `glue()` function from MyST-NB:\n", "\n", "1. **`name`**: Mandatory, the name under which the Bokeh figure should be stored.\n", "2. **`variable`**: Mandatory, the Bokeh figure to glue into the output.\n", "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.\n", "\n", "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.\n", "\n", "The example below shows how to glue and paste Bokeh figures." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from bokeh.plotting import figure\n", "from myst_nb_bokeh import glue_bokeh" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "p = figure(plot_width=300, plot_height=300)\n", "p.circle(range(1, 10), range(10, 1, -1));" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# When display is False or omitted, the figure is not displayed in this cell's output\n", "glue_bokeh(\"bokeh_plot\", p)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once the figure is glued into the output, you can paste it using the [`{glue:}`, `{glue:any}`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types), and [`{glue:figure}`](https://myst-nb.readthedocs.io/en/latest/use/glue.html#the-glue-figure-directive) 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:\n", "\n", "::::markdown\n", ":::{glue:} bokeh_plot\n", ":::\n", "::::\n", "\n", ":::{glue:} bokeh_plot\n", ":::\n", "\n", "We can also use the `{glue:figure}` directive to add a caption and cross-referencing. If you want to paste the same figure twice, it needs to be glued under a new name. Otherwise the `
` HTML element which contains the first pasted figure will simply add a second copy of the plot.\n", "\n", "::::markdown\n", ":::{glue:figure} bokeh_plot_2\n", ":name: bokeh_figure\n", "\n", "The caption for this figure goes here.\n", ":::\n", "::::" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "glue_bokeh(\"bokeh_plot_2\", p)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ":::{glue:figure} bokeh_plot_2\n", ":name: bokeh_figure\n", "\n", "The caption for this figure goes here.\n", ":::" ] } ], "metadata": { "interpreter": { "hash": "3013979006aa15af28970a4c55aeb47b79c549e9010c67c1d062fa6b519563cb" }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.5" } }, "nbformat": 4, "nbformat_minor": 2 }