I'm putting together a PR now which just strips out the part where we verify that references are still missing – that should reduce/remove? race conditions, at the expense of being too-permissive, but I think that's a good tradeoff to have.

Scrolling through the json file, it looks like some of them are clearly incorrect use of single backtick (of which I am responsible for a fair number of coming into the code base...), some are modules being picked up as objects, and some are objects that are missing the correct scoping.

We need to understand https://www.sphinx-doc.org/en/1.5/domains.html#cross-referencing-python-objects and in particular the heuristics around:

Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python’s codecs module, :py:func:open always refers to the built-in function, while :py:func:.open refers to codecs.open().

A similar heuristic is used to determine whether the name is an attribute of the currently documented class.

Also, if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:.TarFile.close references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.

and demonstrate how to fix a few of them.

We are planning a sprint/hackathon in NYC for the fall that this may be a good burn-down list of tasks for first time contributors.

I skimmed through the file, a lot of them are

• code using single backticks -> use double backticks.
• old API that has been deprecated and then removed -> use double backticks.
• modules: use :mod:`...`
• semi-qualified names without the leading "matplotlib.somemodule": try putting just a single dot in front, if there is no ambiguity sphinx will resolve the reference, otherwise, if there's an ambiguity (two APIs with the same trailing name), add the submodule name (either `.somemodule.Foo` which will print out as somemodule.Foo, or `~.somemodule.Foo` which will print out as Foo).
• typos: fix them

That should already cover quite a few entries.

So what am I doing wrong in #14917?

One issue with the line numbers is if code is added or removed above the error I think we will need to update the json file which is not great....

I found that I now get lots of warnings about references already being fixed when building the docs locally with sphinx 1.8.5, sphinx_gallery 0.5.0dev from the current matplotlib master. This could mean that sphinx_gallery is responsible for some breakages and fixed them in the meantime.

If I am understanding how this works correctly, we can only ignore the a given (domain, key) globally, but we are doing the book keeping at the line level.

When we fix a key, we should do a grep on the hole code base to find all instances of it (or just read the list of locations from the json).

That is believable that sphinx gallery, I am definitely in favor of #15043 if that is the case.

Actually it could also be a bug (or misuse from my side?) in the missing_references.py that is responsible for those warnings being triggered. At least I get an error at the very end triggered by

saying

OSError: [WinError 123] Die Syntax für den Dateinamen, Verzeichnisnamen oder die Datenträgerbezeichnung ist falsch: 'd:\\data\\computer\\entwicklung\\python\\matplotlib\\source\\matplotlibgit\\matplotlib\\lib\\matplotlib\\animation.py:docstring of matplotlib.animation.AVConvBase.args_key:1:<autosummary>'

#15048 would fix the error. All the warnings however stay. And they are not related to the sphinx_gallery version. (I tested with sphinx_gallery 0.4.0 now and they persists.)

I would like to investigate these errors more – unfortunately, I am away from a reliable internet until next weekend, so I can't take a serious look until then...

I am going to close this, master branch has been mostly non-broken and I think we have a decent understanding of what these problems are (and there have been some PRs to start fixing them).