Sphinx emits "WARNING: py:class reference target not found" with numpydoc 1.1.0

[pllim]

Hi, thank you for the very useful numpydoc package! The astropy package is a long time user of numpydoc.

Unfortunately, by upgrading from numpydoc 1.0.0 to 1.1.0, we are getting many warnings that start with WARNING: py:class reference target not found.... We also use sphinx-automodapi, where "members that a class inherits from a base class are included in the generated documentation." Hence, a class that subclasses, say, dict, gets all the member doctrings from dict methods (unless overwritten).

Such inheritance has never been a problem until numpydoc 1.1.0. Can you please advise on how we can fix these warnings? Thank you!

[larsoner]

In MNE our quick fix was to subclass dict with compatible docstrings:

https://github.com/mne-tools/mne-python/pull/7943/files#diff-2d8dde20d562ff576ffc43eb2c36df09R1099

I think the underlying issue is actually with autodoc or something trying to :class: link anything following -> in a function summary line, but I haven't fully verified this or made it into a minimal example.

Another quick fix option might be to add another autodoc processing step that converts -> into a Unicode arrow or something that will be ignored by whatever is trying to :class: what follows it. But this would also just be a hack...

[mhvk]

Same problem for all astropy affiliated packages... Unfortunately, unlike other link matching problems, it doesn't seem to help to list either the python class or the subclass in nitpick_ignore. Maybe as a short-cut it is possible to respect items in that list?

[mhvk]

I guess another option would be to allow failure on warnings on docstrings that are actually inside the code base, but non-failure on anything that comes from outside. Or inherited vs non-inherited or so. Tricky!

[larsoner]

Unfortunately, unlike other link matching problems, it doesn't seem to help to list either the python class or the subclass in nitpick_ignore

This is arguably a Sphinx bug, too. This one might actually be possible to fix at the Sphinx end so it ends up in a 3.x release, I'l look into it...

[mhvk]

@larsoner - thanks, the ignoring of the nitpicking does indeed seem a Sphinx bug. Over at astropy/astropy#10524 (comment), there was a suggestion that perhaps it has to do with the fact that the docstring in question includes a single quote. (Though, obviously, that could be a red herring.)

[larsoner]

For me this works fine actually:

nitpick_ignore = [
    ("py:class", "None.  Remove all items from D."),
    ("py:class", "a set-like object providing a view on D's items"),
    ("py:class", "a set-like object providing a view on D's keys"),
    ("py:class", "v, remove specified key and return the corresponding value."),  # noqa: E501
    ("py:class", "None.  Update D from dict/iterable E and F."),
    ("py:class", "an object providing a view on D's values"),
    ("py:class", "a shallow copy of D"),
]

To me it's a consistency problem that CPython and Sphinx need to decide if these are always classes, or Sphinx needs to be smarter about linking them, or we just need to live with ignoring them in projects that use nitpicky = True and subclass dict. But in any case I think we handle strings more generally / better than before, and this seems to have exposed an issue upstream, so shouldn't do anything at the numpydoc end.

Okay to close as this is a sufficient fix and should probably be fixed upstream (by autodoc or by CPython actually making these linkable)?

[mhvk]

@larsoner - yes, indeed, that works! I clearly had understood neither how to read the warning, nor how nitpick_ignore actually works... Thanks so much! (@pllim - this works in my package, so I suspect it will work in astropy too - I'll let you close this, though)

[pllim]

I was going to close if astropy/astropy#10530 works but looks like it is closed already. Thanks for the fix, @larsoner !

[pllim]

Belated update: #275 (comment) works! Needed to do some fixing that @astrofrog pointed out but other than that, it's green again. Thanks!