pythonpython-sphinxcpythonautodoc

Sphinx: Autodocs for classes inheriting from base classes implemented in C

I am running into an error/warning when inheriting from collections.deque. Sphinx complains:

utils.py:docstring of utils.Test.count:1: WARNING: py:class reference target not found: integer -- return number of occurrences of value

For this example, utils.py only contains

from collections import deque

class Test(deque):
    pass

My best guess is that this might be caused by deque being implemented in C, since integer is not a valid Python type. Looking around a bit, I found this line in the CPython source of collections, which could be exactly that part, should my hypothesis be correct. But I have no clue about CPython, the inner workings of Sphinx autodoc and the boundary between those worlds.

Is there a good solution to correcting this, whether in the annotation of CPython or the autodoc plugin?

Solution

  • It seems I was more or less on the money. integer is used elsewhere and seems to work, but more importantly Sphinx expects docstrings to follow the example outlined in PEP 7, which suggests signatures to be placed on the first line (followed by a line break before any other documentation). So it looks for a class named by the whole string between -> and \n, in my case being integer -- return number of occurrences of value.

    The workaround is to put all those strings into nitpick_ignore:

        # Wrong docstrings in the CPython source of collections.queue
    ("py:class", "-- reverse *IN PLACE*"),
    ("py:class", "integer -- return first index of value."),
    ("py:class", "integer -- return number of occurrences of value"),
    ("py:class", "-- insert object before index"),
    ("py:class", "-- remove first occurrence of value."),
    ("py:class", "-- size of D in memory, in bytes"),
    ("py:class", "-- return a reverse iterator over the deque"),

    A proper fix would be to change the documentation in the CPython code accordingly.

    I was about to do that, when I found out my coworker beat me to it by 2 weeks. But on the issue he opened, a core developer argues that this scheme is nothing but an example and that the documentation is only required to be human readable as opposed to specifying the exact types. So it doesn't look like there is going to be a fix anytime soon.