Embedding matplotlib plots in Sphinx: how to show documentation

Question

I have some ipynb documentation with matplotlib plots shown inline by %matplotlib inline directive.

And I have my Sphinx documentation when I try to show my notebook with inline-drawn plots. I try to use

ipython nbconvert shalom.ipynb --to rst

But alas, it does give me an RST without of any inline graphics. With only code listings.

Cannot you tell me, how to generate Sphinx documentation with already-rendered plots.

I know that it's possible.

Answer 1

You need to use the Sphinx extensions for embedded plots, math and more

Sphinx is written in python, and supports the ability to write custom extensions. We've written a few for the matplotlib documentation, some of which are part of matplotlib itself in the matplotlib.sphinxext module, some of which are included only in the sphinx doc directory, and there are other extensions written by other groups, eg numpy and ipython. We're collecting these in this tutorial and showing you how to install and use them for your own project. First let's grab the python extension files from the sphinxext directory from git (see Fetching the data), and install them in our sampledoc project sphinxext directory:

You will need to modify your conf.py to include:

extensions = [
          'matplotlib.sphinxext.mathmpl',
          'matplotlib.sphinxext.only_directives',
          'matplotlib.sphinxext.plot_directive',
          'matplotlib.sphinxext.ipython_directive',
          'sphinx.ext.autodoc',
          'sphinx.ext.doctest',
          'ipython_console_highlighting',
          'inheritance_diagram',
          'numpydoc']