在sphinx文档中嵌入ipython笔记本

Question

我正在为自己的项目编写API文档。 我发现这个很酷的documentation（yt项目）直接使用ipython笔记本来给出示例。当我在 bitbucket 上查看他们的文档存储库时，一个相关的第一个似乎非常简单：

.. notebook:: An_example_notebook.ipynb

但是，当然，这对我不起作用。我不确定“笔记本”是否是固有的块类型。也许“笔记本”块需要外部包。实际上，当我在 sphinx 文档中搜索“笔记本”时，我得到的结果为零。

如果我可以直接使用我的笔记本（无需转换）来举例，那将使生活变得更加轻松。 但我不知道如何才能实现这一目标。

Answer 1

nbsphinx

是一个 Sphinx 扩展，为

*.ipynb

文件提供源解析器。

安装 nbsphinx：

pip install nbsphinx --user

编辑您的

conf.py

并将

'nbsphinx'

添加到扩展程序中。

编辑您的

index.rst

并将

*.ipynb

文件的名称添加到

toctree

。

在执行上述操作后

按照此链接

运行狮身人面像！

Answer 2

另一种意见是使用

myst-nb

代替

nbsphinx

。不幸的是，

nbsphinx

需要安装

pandoc

。此外，

nbsphinx

要求笔记本的标题使用连字符 (-) 而不是空格。而

myst-nb

没有这些要求并且可以正常工作。

1. 安装

   myst-nb

   ：

   pip install myst-nb

2. 将

   "myst_nb"

   添加到

   conf.py

   文件的扩展名中，以读取

   md

   文件和

   ipynb

   文件。请注意，您需要从扩展中删除

   "myst_parser"

   （仅读取

   md

   文件）以避免此错误：

   Config value 'myst_commonmark_only' already present

   。
3. 现在将您的笔记本文件包含在

   toctree

   指令中。请注意，您不必提供带有文件名的扩展名，因为无论哪种方式都可以。

更多信息：myst-nb.readthedocs