WARNING: toctree contains reference to nonexisting document error with Sphinx

Question

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.

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