包括带有nbsphinx的笔记本失败

Question

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

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

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

我的索引.rst 中的 toctree 如下：

.. 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

狮身人面像是否可能尝试将文件作为 .rst 文件包含？nbsphinx文档只是说我必须安装软件包，向扩展添加nbsphinx，然后我将能够将我的文档添加到toctree。我没有找到与此问题相关的任何信息。

Answer 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

最重要的是，您需要确保笔记本包含标题，如上面的答案中所述。

Answer 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。