nb2plots 0.7.2

它做什么

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扩展，这些扩展会在Sphinx构建过程中从ReST源生成Python代码文件和Jupyter笔记本。当您将Nb2plots ReST指令code-links添加到您的ReST页面时，它将导致Sphinx构建生成您的页面的Python代码和笔记本版本，并添加下载链接到这些版本。

.. code-links::

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

让我看看它的样子

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

对于使用Nb2plots广泛的适度规模的教学网站，请参阅https://matthew-brett.github.io/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文件。

Github Actions会自动在Python版本3.8到3.11下测试代码。

最新发布的版本在https://pypi.python.org/pypi/nb2plots

测试

• 安装nb2plots

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

  pip install pytest mock scripttester

• 使用以下命令运行测试

  py.test --pyargs nb2plots

支持

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