包括笔记本与nbsphinx失败

Question

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

我想包含的文件是 demo.ipynb 使用扩展名 nbsphinx. 它成功地安装在我的电脑上。在我的conf.py文件中，Sphinx的extensions变量包含以下几行。

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

我的index.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

Sphinx是否可能尝试将该文件包含为.rst文件？在我编译文档时，我总是得到以下警告：Sphinx是否可能尝试将文件包含为.rst文件？nbsphinx 文档只是说我必须安装软件包，添加 nbsphinx 的扩展，然后我就可以将我的文件添加到。toctree. 我没有找到任何与这个问题相关的信息。

Answer 1

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

只需在你的笔记本中创建一个Markdown单元格，里面写上类似这样的内容。

# My Title

参见 https:/github.comspatialaudionbsphinxissues310。 和 https:/github.comspatialaudionbsphinxpull401。.

现在有一个更好的警告，见 https:/github.comspatialaudionbsphinxpull402。.