python - 警告：toctree 包含对 Sphinx 不存在文档错误的引用

Question

几天前我开始使用 Sphinx 来记录一个 python 包，我得到了一个似乎很常见的错误，但我找不到解决方案。

我使用 sphinx-quickstart 来设置所有内容。我使用“doc/”作为文档根位置。包含我的包的文件夹设置为：

myfolder/
    doc/
    mypackage/
        __init__.py
        moprob.py
        ...

快速启动后，我将 conf.py 中的路径编辑为：

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

然后我将包中的一个脚本添加到 index.rst 以查看 sphinx 的工作原理。

 .. toctree::
   :maxdepth: 2
   :caption: Contents:

   mypackage/moprob

我得到的错误代码：

.../index.rst:9: WARNING: toctree contains reference to nonexisting document u'mypackage/moprob'

我尝试过的解决方案：

将 sphinx.ext.napoleon 添加到扩展列表中，因为我所有的文档字符串都是使用 numpy 格式编写的。错误并没有消失。我还将拿破仑扩展名放在 autodoc 之后，因为其中一个帮助页面建议这样做。

扩展 = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
将 numpydoc_show_class_members = False 添加到 conf.py。我把它直接放在扩展下面。这也没有帮助。
文件夹位置的几种不同配置。我还尝试将根位置设置为 myfolder 并将源设置为 mypackage 并将构建设置为 doc。没有一个有效。

你有什么想法可以帮助我吗？

score 9 · Accepted Answer

toctree指令包含对 reStructuredText 文档的引用，而不是 Python 脚本或模块。Sphinx 期望有一个mypackage/moprob.rst文件（在doc文件夹中），但没有。因此错误。

要快速获得一些有意义的输出，请创建 mypackage/moprob.rst 文件。在其中添加标题和自动模块指令：

moprob module
=============

.. automodule:: mypackage.moprob
   :members:

然后再次运行 sphinx-build。

1 回答 1