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

2022-04-21 00:00:00 python python-sphinx toctree numpydoc

问题描述

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

我使用了狮身人面像-快速入门来设置一切。我使用"doc/"作为文档的根位置。包含我的包的文件夹设置为:

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

快速入门后,我将conf.py中的路径编辑为:

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

然后,我将包中的一个脚本添加到index.rst,以查看Shinx是如何工作的。

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

   mypackage/moprob

我得到的错误代码:

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

我尝试过的解决方案:

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

    扩展=[‘sphinx.ext.autodoc’, ‘sphinx.ext.napolon’]

  2. 正在将numpydoc_show_CLASS_MEMBERS=FALSE添加到conf.py。我把这个放在分机的正下方。这也没有帮助。

  3. 文件夹位置的几种不同配置。我还尝试将根位置设置为myFolders,并将源代码设置为mypackage,将构建设置为doc.没有一个有效。

您有什么可能对我有帮助的想法吗?


解决方案

toctree指令包含对reStructredText文档的引用,而不是对其脚本或模块的引用。Sphinx希望有一个mypackage/mopro.rst文件(在文档文件夹中),但实际上没有。因此出现错误。

要快速获得一些有意义的输出,请创建mypackage/mopro.rst文件。在其中添加标题和automodule指令:

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

.. automodule:: mypackage.moprob
   :members:

然后再次运行sphinx-Build。

相关文章