pymor-nb2plots 0.7

它能做什么

nb2plots 将 Jupyter 笔记本转换为 ReST 文件，以便于 Sphinx 使用，然后再转换回来。

Nb2plots 假设 ReST 文档将成为您 Sphinx 网页的源文件，同时也是未来笔记本版本的源文件。笔记本可以作为精炼的 ReST 页面的草稿，以及 Sphinx 构建过程的输出格式。为什么？请继续阅读。

为什么将 Jupyter 笔记本转换为 Sphinx？

Jupyter 笔记本在快速编写教程或准备软件演示时非常有用。但当你想要对笔记本进行非平凡编辑，或需要笔记本不具备的功能时，例如灵活的交叉引用、可扩展的标记等，问题就出现了。笔记本在使用版本控制时也相当痛苦。这些时刻让你希望你的笔记本处于一个标准的可扩展文本格式，例如 ReST。

您可以使用标准 nbconvert 命令将笔记本转换为 ReST，但这会产生相当丑陋的 ReST，并且您会丢失笔记本擅长执行的代码和图形生成。

欢迎使用 Nb2plots。该 nb2plots 命令可以将笔记本转换为特殊格式的 ReST 页面。使用时：

nb2plots notebook.ipynb > with_plots.rst

Nb2plots 将您的笔记本转换为不太丑陋的 ReST，其中代码单元变成 ReST 文件中的 nbplot 指令。

具体来说，一个类似这样的笔记本代码单元

a = 1

在 ReST 文档中变成（如下）

.. nbplot::

    >>> a = 1

nbplot 指令在 Sphinx 构建您的 ReST 文件时运行包含的代码，并嵌入代码生成的任何图形的结果。实际上，nbplot 是 matplotlib 图形指令 的扩展和编辑版本。构建页面时运行所有代码并重新生成图形，您可以得到笔记本体验的大部分可重复性。

您还可以在您的页面上运行标准的 Sphinx doctest 扩展来检查代码单元的 doctest 输出。

您的笔记本 ReST 版本有许多优点——它更容易在您喜欢的文本编辑器中编辑，并且您可以通过多种不同的方式扩展和配置代码的执行和显示。例如，如果您认为某些代码单元（Nbplot 指令）中的代码对您要说明的点不感兴趣，但您仍然想要生成的图形，您可以隐藏这些代码单元。您还可以配置 Nbplot 指令以运行不同配置下的不同代码。有关这些选项，请参阅 nbplots 文档。但是——当从笔记本到 Nb2plots ReST 文档时，您会丢失什么？

我也想要笔记本和 .py 文件

您可能还希望有一个用户可以执行的文档版本。也许页面构建正在生成一些复杂的错误或警告，您想交互式地试验页面中的代码。也许您的用户已经习惯了笔记本，并且更喜欢该格式中的代码。

Nb2plots 还包含导致 Sphinx 构建从 ReST 源生成 Python 代码文件和 Jupyter 笔记本的 Sphinx 扩展。当您将 Nb2plots ReST 指令 code-links 添加到您的 ReST 页面时，它将导致 Sphinx 构建创建页面 Python 代码文件和笔记本版本，并添加到这些版本的下载链接。

.. code-links::

有关详细信息，请参阅 code-links 文档。

展示一下它的样子

对于一个非常简单的示例，请参阅 工作示例。

对于一个大型的教学站点，该站点广泛使用 Nb2plots，请参阅 https://matthew-brett.github.com/teaching。

安装

pip install nb2plots

您需要安装并可用 Pandoc 作为 pandoc 命令。

要在 OSX 上安装 Pandoc，我们推荐使用 homebrew

brew install pandoc

配置

将以下内容添加到您的 Sphinx conf.py 文件中

extensions = ["nb2plots"]

有关各种 conf.py 配置设置的详细信息，请参阅 nbplots 文档。

代码

请参阅 https://github.com/matthew-brett/nb2plots

在源分布中发布于 BSD 两条款许可——请参阅源分布中的 LICENSE 文件。

travis-ci 自动在 Python 2.7、3.3 到 3.5 版本下测试代码。

最新发布版本可在 https://pypi.python.org/pypi/nb2plots 找到

测试

• 安装 nb2plots

• 安装pytest测试框架、mock包和scripttester包。

  pip install pytest mock scripttester

• 运行测试

  py.test --pyargs nb2plots

支持

请在nb2plots问题跟踪器上提出问题。