Sphinx autosummary "toctree contains reference to nonexisting document" warnings

Question

I am trying to automatically create api docs for a large python codebase using Sphinx.

I have tried using build_modules.py and sphinx-apidoc. With either one, I can get rst docs successfully created in my output directory for the packages and top-level modules.

However, when I build using

make html

it gives thousands of errors of this type:

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

for every single class and method in the codebase. With some experimentation I think I have discovered that the autosummary/autoclass directives are creating toctrees that expect there to be rst files for every class and method.

Other than the warnings, the documentation seems to work well, but I would like to get rid of them and I think I may have misconfigured something.

I have also tried nipype/tools to much the same effect.

I modified apigen.py and build_modref_templates.py to create rst stubs for each of these "missing" documents, with autoclass/autofunction/automethods as appropriate. However, the build takes quite a long time (10 minutes) and eventually crashes due to memory errors on the last build step.

Here is an example module rst file that creates all the warnings:

src Package
===========

:mod:`src` Package
------------------

.. automodule:: src.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example1` Module
------------------------------------

.. automodule:: src.Example1
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example2` Module
------------------

.. automodule:: src.Example2
    :members:
    :undoc-members:
    :show-inheritance:

Thanks for any advice on how to make these warnings resolve! I would like to stay away from any solution that involves modifying the sphinx site-package files.

Moresque

Are you sure you have a toctree entry pointing to the generated docs? e.g. to the src package documentation you posted above? – Monosyllabic

Related unresolved issue: github.com/numpy/numpydoc/issues/69 – Stepchild

Answer 1

Sorry for such a late answer (if it can be considered that) but I found this link that discusses what may be happening to you:

https://github.com/phn/pytpm/issues/3#issuecomment-12133978

The idea that if you have some special Doc scraper in your documentation code that is building autosummary documentation after autosummary has already run may be something to look into if you are still having this issue. Although, I'm not sure how much help this will be.

The key from the link is to add: numpydoc_show_class_members = False to conf.py

Macaluso

If you do that, that removes the method table, though :( – Zicarelli

Has anyone discovered a solution that doesn't remove the method table? I cannot switch to sphinx.ext.napoleon because that does not seem to support the same feature as numpydoc_use_plots. – Mcclendon

> Has anyone discovered a solution that doesn't remove the method table? Yes, copy the matplotlib/sphinxext/plot_directive.py into your doc local directory and use that as an additional sphinx directive. – Gannon

Answer 2

I just encountered this issue too and spend hours on this, The following worked for me:

Sphinx can be fussy, and sometimes about things you weren’t expecting. For example, you well encounter something like:

WARNING: toctree contains reference to nonexisting document u'all-about-me'
...
checking consistency...
<your repository>/my-first-docs/docs/all-about-me.rst::
WARNING: document isn't included in any toctree'

Quite likely, what has happened here is that you indented all-about-me in your .. toctree:: with four spaces, when Sphinx is expecting three.

Source: docs!

Infidel

Finally finding the issue ; tears of joy down my face – Ynes

Answer 3

If you are using the numpydoc extension, you could consider removing it and using sphinx.ext.napoleon instead.

Since version 1.3, Numpy and Google style docstrings are in fact supported by this builtin extension.

Removing numpydoc and using sphinx.ext.napoleon in your conf.py will therefore probably solve your problem.

---

Sources

• Napoleon - Marching toward legible docstrings
• Sphinx Doc - Support for NumPy and Google style docstrings

Hitandrun

Answer 4

In Sphinx 5.3, your indentation needs to be consistent (the number of spaces does not seem to matter).

Three space indentation will work:

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

   admin/index

Two space indentation will also work:

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

  admin/index

However if the indentation is inconsitent, with :maxdepth: indented with three spaces, but admin/index indented with two spaces as shown below...

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

  admin/index

...then you will likely get warnings:

WARNING: toctree contains reference to nonexisting document ' :maxdepth: 2'
WARNING: toctree contains reference to nonexisting document ' :caption: Contents:' 

Mesne

Answer 5

When using numpydoc, adding the Methods heading to the class docstring may resolve these warnings.

Example from the numpydoc docs: https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring

class Photo(ndarray):
    """
    Array with associated photographic information.

    ...

    Attributes
    ----------
    exposure : float
        Exposure in seconds.

    Methods
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

    """

In my opinion, it is a bit too redundant, but it does allow you to keep the methods table.

Otherwise, as an alternative you can use something like this (but the methods table will be removed)

:modname:`src`
---------------------------
.. automodule:: src.__init__
   :show-inheritance:
   :private-members:
   :undoc-members:
   :special-members: __call__
   :inherited-members:

Kind of odd that :members: causes a problem, but not :private-members:.

For reference, there is an open issue on numpydoc regarding this since 2016. https://github.com/numpy/numpydoc/issues/69

Macula