WARNING: toctree contains reference to nonexisting document error with Sphinx

问题

I started using Sphinx a couple of days ago to document a python package, and I'm getting what seems to be a common error, but I cannot find a solution for it.

I used the sphinx-quickstart to set everything up. I used "doc/" for the documentation root location. The folder containing my package is setup as:

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

After the quick start, I edited the path in conf.py to be:

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

Then I added one of the scripts in my package to index.rst to see how sphinx works.

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

   mypackage/moprob

The error code I get:

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

Solutions I have tried:

Adding sphinx.ext.napoleon to the extensions list since all of my doc strings are written using the numpy format. The error did not go away. I also put the napoleon extension after autodoc because one of the help pages suggested that.

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
Adding numpydoc_show_class_members = False to conf.py. I put this directly below the extensions. This also did not help.
A couple of different configurations for folder locations. I've also tried setting the root location to be myfolder and setting the source to be mypackage and the build to be doc. None has worked.

Do you have an idea that might help me?

回答1:

The toctree directive contains references to reStructuredText documents, not Python scripts or modules. Sphinx expects there to be a mypackage/moprob.rst file (in the doc folder), but there isn't one. Hence the error.

To quickly get some meaningful output, create the mypackage/moprob.rst file. Add a heading and an automodule directive in it:

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

.. automodule:: mypackage.moprob
   :members:

Then run sphinx-build again.

来源：https://stackoverflow.com/questions/45195363/warning-toctree-contains-reference-to-nonexisting-document-error-with-sphinx

标签

python

python-sphinx

toctree

numpydoc