pythonpython-sphinxtoctreenumpydoc

WARNING: toctree contains reference to nonexisting document error with Sphinx


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:

  1. 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 documentation pages suggested that.

    extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.napoleon']
    
  2. Adding numpydoc_show_class_members = False to conf.py. I put this directly below the extensions but it also did not solve the error.

  3. 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.


Solution

  • 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.