Package: pymor-nb2plots
See the nb2plotsdocumentationfor more information.What it doesnb2plotsconvertsJupyternotebooks toReSTfiles forSphinx, and back
again.Nb2plots assumes that the ReST document will become the source for your Sphinx
web pages, but also for future versions of the notebook.  The notebook may
serve as a draft for the polished ReST page, and an output format from the
Sphinx build.  Why? Read on.Why convert Jupyter notebooks to Sphinx?Jupyter notebooks are just what the doctor ordered when hacking up a quick
tutorial, or preparing a software demo.  The problems start when you want to
do not-trivial edits to the notebooks, or you need features that notebooks
don’t have, such as flexible cross-referencing, extensible markup, and so on.
Notebooks are also painful to use with version control.  These times make you
wish your notebook was in a standard extensible text format, such asReST.You could convert your notebook to ReST using the standardnbconvertcommand, but this gives rather ugly ReST, and you lose all the nice code
execution and figure generation that the notebook is good at.Enter Nb2plots.  Thenb2plotscommand converts notebooks to specially
formatted ReST pages. Use with:nb2plots notebook.ipynb > with_plots.rstNb2plots converts your notebook to not-very-ugly ReST, where the code cells
becomenbplotdirectives in your ReST file.Specifically, a notebook code cell like this:a = 1becomes (in the ReST document):.. nbplot::

    >>> a = 1Thenbplotdirectives run the contained code when Sphinx builds your ReST
files, and embed the results of any plots that your code makes.  Actually,nbplotis an extended and edited version of thematplotlib plot
directive.  Building your pages runs all the code and regenerates the
figures, and you get much of the reproducible goodness of the notebook
experience.You can also run the standard Sphinxdoctestextension over your pages to
check the doctest output of the code cells.The ReST version of your notebook has many advantages - it is easier to edit
in your favorite text editor, and you can extend and configure the execution
and display of the code in several different ways.  For example, you can hide
some code cells (Nbplot directives) if the code is not interesting to your
point, but you still want the generated figure.  You can configure your Nbplot
directives to run different code for different configurations.  For these
options, seenbplots documentation.  But - what do you lose, when going from
a notebook to a Nb2plots ReST document?I want notebooks and .py files tooYou may also want a version of your document that your users can execute.
Perhaps the page build is generating some tricky errors or warnings, and you
want to experiment with the code in the page interactively.  Perhaps your
users are used to notebooks, and prefer the code in that format.Nb2plots also contains Sphinx extensions that cause the Sphinx build to
generate Python code files and Jupyter notebooks from the ReST source.  When
you add the Nb2plots ReST directivecode-linksto your ReST page, it will
cause the Sphinx build to create a Python code file and notebook versions of
your page, and adds download links to these versions:.. code-links::Seecode-links documentationfor details.Show me what it looks likeFor a very simple example, seeworked example.For a moderate-sized teaching site that makes extensive use of Nb2plots, seehttps://matthew-brett.github.com/teaching.Installationpip install nb2plotsYou will needPandocinstalled and available as thepandoccommand.To install Pandoc on OSX, we recommendhomebrew:brew install pandocConfigurationAdd the following to your Sphinxconf.pyfile:extensions = ["nb2plots"]Seenbplots documentationfor the variousconf.pyconfiguration settings.CodeSeehttps://github.com/matthew-brett/nb2plotsReleased under the BSD two-clause license - see the fileLICENSEin the
source distribution.travis-cikindly tests the
code automatically under Python versions 2.7, and 3.3 through 3.5.The latest released version is athttps://pypi.python.org/pypi/nb2plotsTestsInstallnb2plotsInstall thepytesttesting framework, themockpackage, and thescripttesterpackage.pip install pytest mock scripttesterRun the tests with:py.test --pyargs nb2plotsSupportPlease put up issues on thenb2plots issue tracker.