Repository navigation
[Doc]: Spurious references from API to gallery examples #22036
Description
Documentation Link
Problem
My understanding is that the API reference should only include links to gallery examples if the given API function is listed in the .. admonition:: References block of the example, see documentation and e.g. #19233 (comment). However, links seem to be generated for any function in the example, see for instance set_axis_off where set_axis_off is included in the references list in only 2 of the 9 linked gallery examples. plot links to even 176 examples (there's hardly any example that's not linked to from there).
(this is kind of the reverse of #19715)
Suggested improvement
Add links only to those gallery examples that explicitly list the given function in their references block.
Matplotlib Version
3.6.0.dev888+g25a54a4fef.d20211129
Activity
jklymak commentedon Dec 22, 2021
No that is not correct. The admonition was added because many references were not being made, but the automatic references are indeed meant to show up this way.
StefRe commentedon Dec 22, 2021
@jklymak
so that means that I should list in the admonition only those functions that are not automatically turned into a link by sphinx?
is this really useful?
If this is indeed the intended behavior then I think the documentation should be amended, shouldn't it?
jklymak commentedon Dec 22, 2021
I don't think it makes any practical difference to people adding admonitions. They can list things here, or not, based on that advice, some of which will be duplicate with the automatic cross linking. I suppose you could make the case that we get rid of the automatic cross links, but I'm personally of the opinion more cross linking is good.
StefRe commentedon Dec 22, 2021
OK, so we can close this issue or should we wait for @timhoffm (who wrote the above mentioned paragraph in #19232) to weigh in?
timhoffm commentedon Dec 23, 2021
What is linked and what not is determined by sphinx-gallery (see https://sphinx-gallery.github.io/stable/configuration.html#references-to-examples):
(1) depends on how good the parser can infer types. Sometimes it works sometimes it doesn’t.
If it does we get links to the example.
The references admonition is intended to list the most relevant API. This has two purposes:
A) It‘s an explicit summary of API worth mentioning in the example.
B) It makes sure that that API is linked to the example via (2) from above.
Whether one adds something to the admonition should mainly be determined by A) and not depend on whether the autodetection (1) works or not.
One could argue that the flaky auto-detection from doe (1) is undesirable. Suppressing it would need a respective option in sphinx-gallery. I‘m not aware that it exists. If it did, I‘d have a slight favor of suppressing the autogenerated links.
timhoffm commentedon Dec 23, 2021
So to summarize: I think the request here is reasonable, but would need action primarily in sphinx-gallery.