Search code examples
pythonpython-2.7python-sphinxtoctreesphinx-napoleon

Sphinx autosummary "toctree contains reference to nonexisting document" warnings

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.

Solution

  • 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