Repository navigation
Sphinx emits "WARNING: py:class reference target not found" with numpydoc 1.1.0 #275
Description
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!
Activity
larsoner commentedon Jul 3, 2020
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 commentedon Jul 4, 2020
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 commentedon Jul 4, 2020
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 commentedon Jul 6, 2020
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.xrelease, I'l look into it...mhvk commentedon Jul 6, 2020
@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 commentedon Jul 6, 2020
For me this works fine actually:
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 = Trueand subclassdict. 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 thenumpydocend.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 commentedon Jul 6, 2020
@larsoner - yes, indeed, that works! I clearly had understood neither how to read the warning, nor how
nitpick_ignoreactually 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 commentedon Jul 6, 2020
I was going to close if astropy/astropy#10530 works but looks like it is closed already. Thanks for the fix, @larsoner !
pllim commentedon Jul 6, 2020
Belated update: #275 (comment) works! Needed to do some fixing that @astrofrog pointed out but other than that, it's green again. Thanks!