笔记本Sphinx扩展

安装

此包可在pypi上找到： https://pypi.python.org/pypi/RunNotebook

使用pip进行安装

pip install RunNotebook

将扩展添加到您的conf.py

extensions = [
    # Import both
    'RunNotebook',

    # or import each directive individually
    # 'RunNotebook.notebook_sphinxext',
    # 'RunNotebook.notebookcell_sphinxext',
    # ...
]

在conf.py中进行可选配置

# Run notebook configuration

# The template used when exporting from nbconvert
#   full  - Outputs the full HTML document [Default]
#   basic - Outputs a single div (with no additional resources)
run_notebook_export_template = 'basic'  # Default: 'full'

# Display the source links to the generated evaluated files
run_notebook_display_source_links = False  # Default: True

查看示例Sphinx项目中的conf.py文件，了解如何与您的Sphinx构建集成。

文档中的代码片段

此包包含两个有用的Sphinx扩展： notebook和notebook-cell。这些扩展对于在Sphinx文档中嵌入整个笔记本或单个笔记本单元非常有用。

在过去，在版本控制的文档中包含示例脚本相对简单。例如，可以使用rst code-block指令在sphinx文档中包含代码片段。

.. code-block:: python

   for i in range(5):
     print i

虽然这样做会在sphinx文档中嵌入语法高亮的Python脚本，但它不会运行代码或提供检查代码是否正确的任何设施。

Jupyter笔记本提供了一个强大的环境，用于文献编程，其中代码输入、输出和解释性文本嵌入到单个文档中。将笔记本包含到文档中是很有吸引力的。然而，这种做法也存在一些问题。笔记本的版本控制很困难 - 输出可能会变化，如果笔记本输出包含大量数据，diff可能会迅速增长，产生一个不便的大存储库。此外，更新笔记本需要手动重新评估所有笔记本单元、保存笔记本，如果发生任何更改，则需要提交。评估笔记本的版本控制也不保证笔记本中的代码仍然有效 - 对于一个记录有缺陷的测试覆盖的演变代码库的笔记本来说，这是一个真正的担忧。

使用Sphinx扩展来自动运行笔记本

本包中包含的扩展使得在文档中轻松包含未经评估的笔记本或简短的Python代码片段成为可能。这两个扩展都使用 nbconvert 来脚本化笔记本的评估，并将评估后的笔记本转换为适合嵌入到Sphinx文档中的HTML格式。

依赖关系

此扩展依赖于 Jupyter。

请注意，所有 Jupyter 依赖项（包括可选的）都必须安装。特别是，pandoc 和 node.js 必须可用，因为这些被nbconvert使用。

示例

假设我想在我的文档中内联包含一个名为 example.ipynb 的笔记本。为此，请将以下内容添加到任何Sphinx ReStructuredText文档中

.. notebook:: example.ipynb

在预处理期间，sphinx将评估笔记本，将其转换为HTML，并将它嵌入到文档中，位置是使用notebook指令的地方。

如果整个笔记本没有意义，或者您想将脚本与文档的源紧密关联，则可以使用notebook-cell来嵌入单个单元格的迷你笔记本

.. notebook-cell::

   for i in range(5):
     print i

这将把代码片段转换为笔记本，评估笔记本，然后将结果嵌入到文档中。请注意，notebook-cell目前不接受用户命名空间，因此所有必要的导入都必须包含在源代码中。

请在存储库根目录下的example文件夹中查看使用基本sphinx配置的完整、可工作的示例。

已知问题

这些扩展使用nbconvert HTML输出的“完整”HTML输出版本。这包括完整的笔记本CSS。有一些CSS monkeypatching操作以减少笔记本CSS对文档的影响，这可能会与您的文档主题冲突。如果发现monkeypatching不够健壮，并在您首选的文档主题中存在视觉问题，请通过打开github问题与我联系。