在Sphinx文档中嵌入IPython笔记本

Question

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

.. notebook:: An_example_notebook.ipynb

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

如果我可以直接使用我的笔记本（而无需转换）来举例说明，那将使生活更加轻松。但我无法弄清楚如何实现这一点。

- Hoseung Choi

---

类似于http://nbsphinx.readthedocs.io/en/0.2.8/？ - cel

他们正在使用 https://github.com/ngoldbaum/RunNotebook。 - Matthias

Answer 1

nbsphinx是一个Sphinx扩展程序，提供了对*.ipynb文件的源代码解析。

安装nbsphinx:

pip install nbsphinx --user

请编辑你的conf.py并在扩展中添加'nbsphinx'。

请编辑你的index.rst并将你的*.ipynb文件名称添加到toctree中。

完成以上步骤后，请访问此链接。

最后运行Sphinx！

- pd farhad

---

谢谢，你能提供一份如何引用笔记本的示例吗？到目前为止，我只看到了一个空白页面... :/ - Jirka

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

- Zakariya