警告：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'

我尝试过的解决方案：

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

   扩展名= ['sphinx.ext.autodoc'，'sphinx.ext.napoleon']

2. 向conf.py添加numpydoc_show_class_members = False。我将其直接放在扩展的下方。这也没有帮助。

3. 文件夹位置的几种不同配置。我还尝试将根目录位置设置为myfolder，将源位置设置为mypackage，将内部版本设置为doc。没有一个有效。

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

Answer 1

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

为了快速获得有意义的输出，请创建mypackage / moprob.rst文件。在其中添加标题和automodule指令：

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

.. automodule:: mypackage.moprob
   :members:

然后再次运行sphinx-build。