Sphinx autodoc gives WARNING: py:class reference target not found: type warning

Question

I've got some code that uses a metaclass in python. But when sphinx autodoc is run it is giving the error:

WARNING: py:class reference target not found: type

The error is occuring in a line of an auto generated .rst file:

.. automodule:: API.list.blockList
    :members: # this is the line in error
    :show-inheritance:

And blockList extends API.list.list which has \__metaclass__ set to my metaclass.

From what I can tell sphinx doesn't think that the builtin type class exists. I've tried importing the builtin type to make sphinx realize it's there but that hasn't worked.

If I remove the metaclass assignment from API.list.list, and remove the metaclass from the code then sphinx works just fine.

Answer 1

This is simply a bug in the Python docs themselves--references to some of the Python built-ins (including type) do no resolve correctly (see, for example https://bugs.python.org/issue11975).

To make the warning go away you can add the nitpick_ignore option to your Sphinx config. For example on the Astropy project we have:

nitpick_ignore = [('py:class', 'type')]

In fact, there are enough exceptions that we just put them all in a separate file that we read them out of. See:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/conf.py#L195

and for the exception file itself:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/nitpick-exceptions

Many of the exceptions in the above file are specific to Astropy, but others address some broken references in Python and in Numpy, and may be generically useful.