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.

Midyear

Can you provide a minimum example that triggers this? – Barayon

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.

Wisla

Answer 2

For what it's worth, I get this same error when my docstrings look like this:

def some_function():
    Generic description

    Args:
        arg1: This arg description is so long that it cannot fit on a single line.
        So it spills over onto the next line, but I didn't add a tab.

I think sphinx expects "So it spills..." to be an argument, and it looks for it in the function's arg list, but doesn't find it, then it throws the error.

def some_function():
    Generic description

    Args:
        arg1: This arg description is so long that it cannot fit on a single line.
            I added a tab and now I don't have any problems with sphinx.

Attenuant