How to handle sphinx nitpicky mode · Issue #15042 · matplotlib/matplotlib · GitHub

In general, however, I have some problems with this nitpicky stuff.

It seems noone is currently able to understand the reasons for (most of) the missing references. They might even be caused by bugs upstream. It is hence likely that they won't be fixed soon. Also, if there are upstream fixes required, they might not help because currently the sphinx version used by matplotlib is pinned.
From now on, each time an edit of any of the files that contain missing references in docstrings will require to edit the line numbers, which is not only cumbersome, but clearly a burden we should not load on contributors' shoulders.
The race condition that led to this trouble here will likely reoccur in the future unless all missing references have been fixed at least once.

So is anyone actually optimistic this can be solved anytime soon? If not, I would propose to disable nitpicky for now.

Originally posted by @ImportanceOfBeingErnest in #15034 (comment)

@alexrudy

@ImportanceOfBeingErnest I think you are right, but I would propose something slightly different:

The line number bit was suggested by @anntzer in the original PR. I propose we remove the warnings about unused nitpick ignores by line number – but otherwise leave nitpick turned on.

This will still prevent the addition of "new" incorrect references, but allow any existing missing references to persist. The disadvantage is that it will allow "old" missing reference ignores to persist as well.

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

matplotlib/doc/sphinxext/missing_references.py

Line 108 in 2b31002

fullpath = Path(path).resolve()

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).

How to handle sphinx nitpicky mode · Issue #15042 · matplotlib/matplotlib · GitHub

Repository navigation

How to handle sphinx nitpicky mode #15042

@alexrudy

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

How to handle sphinx nitpicky mode · Issue #15042 · matplotlib/matplotlib · GitHub

Repository navigation

How to handle sphinx nitpicky mode #15042

Description

@alexrudy

Activity

alexrudy commented on Aug 12, 2019

tacaswell commented on Aug 12, 2019

anntzer commented on Aug 12, 2019

ImportanceOfBeingErnest commented on Aug 12, 2019

tacaswell commented on Aug 12, 2019

ImportanceOfBeingErnest commented on Aug 12, 2019

tacaswell commented on Aug 12, 2019

ImportanceOfBeingErnest commented on Aug 12, 2019

ImportanceOfBeingErnest commented on Aug 13, 2019

alexrudy commented on Aug 13, 2019

tacaswell commented on Sep 1, 2019

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions