Using the mpl-interactive directive

Many notebooks have code cells generating matplotlib plots. Nearly all of these have a code cell near the top with the IPython magic command %matplotlib inline or %matplotlib nbagg. This commands tell the notebook to embed the plots inside the notebook rather than generate them in separate windows.

When nb2plots converts a notebook to ReST, it detects these commands, and adds a new directive .. mpl-interactive:: at the matching place in the ReST page. When Sphinx builds the ReST page to HTML, the directive put boilerplate text into the page reminding the user that they may want to use the %matplotlib magic command in the IPython console, or %matplotlib inline when they are running the commands in the Jupyter notebook. The mpl-interactive directive also serves as marker when converting the ReST page to a notebook again; the directive generates a notebook code cell with the %matplotlib inline magic at the matching location, like this:

Hint

If running in the IPython console, consider running %matplotlib to enable interactive plots. If running in the Jupyter Notebook, use %matplotlib inline.

mpl-interactive directive

Directive to handle %matplotlib [inline] in Sphinx, Notebooks

The directive is a marker to tell the Notebook converter to put a %matplotlib inline code cell at this position in the text. Use thusly:

.. mpl-interactive::

With no content (as above), the directive inserts a Hint into the ReST text suggesting %matplotlib in the IPython console, or %matplotlib inline in the Notebook. You can specify some other message with:

.. mpl-interactive::

    Your text here.

The text can be any valid ReStructured text.