包括带有 nbsphinx 的笔记本失败答案

【问题标题】：Including notebook with nbsphinx fails包括带有 nbsphinx 的笔记本失败
【发布时间】：2019-03-22 10:18:37
【问题描述】：

我是 Sphinx 的新手，我想编写 Python 包的文档。我想包含演示文件时遇到问题。

我想使用扩展名nbsphinx 包含文件demo.ipynb。它已成功安装在我的计算机上。我的 Sphinx conf.py 文件中的 extensions 变量包含以下几行：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.napoleon',
    'nbsphinx',
]

我的 index.rst 中的目录树如下：

.. toctree::
   :maxdepth: 3
   :glob:

   demo

当我编译我的文档时，我总是收到以下警告：

PATHTOPACKAGE/docs/source/index.rst:19: WARNING: toctree contains reference to document 'demo' that doesn't have a title: no link will be generated

Sphinx 是否会尝试将文件包含为 .rst 文件？ nbsphinx 文档只是说我必须安装包，将 nbsphinx 添加到扩展中，然后我就可以将我的文档添加到 toctree。我没有找到与此问题相关的任何信息。

【问题讨论】：

Toctree 条目应该是 RST 文件（带有标题/标题）。 sphinx-doc.org/en/master/usage/restructuredtext/…
你可以在那里看到一个可能的解决方案：stackoverflow.com/questions/25866102/…

标签： python jupyter-notebook jupyter python-sphinx toctree

【解决方案1】：

我刚刚再次遇到此问题，并注意到您需要确保您的 source_suffix 配置确实不包含 .ipynb。所以conf.py 应该是这样的

extensions = [
    # ...,
    "nbsphinx"
]
source_suffix = [".rst", ".md"]
# note: do not add .ipynb when nbspinx is enabled, otherwise you get the "missing title" error

最重要的是，您需要确保笔记本包含标题，正如上面的答案中已经指出的那样。

【讨论】：

【解决方案2】：

每个笔记本都需要一个标题。

只需在您的笔记本中创建一个 Markdown 单元格，其中包含如下内容：

# My Title

另请参阅 https://github.com/spatialaudio/nbsphinx/issues/310 和 https://github.com/spatialaudio/nbsphinx/pull/401。

现在有更好的警告，请参阅https://github.com/spatialaudio/nbsphinx/pull/402。

【讨论】：