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.

@jklymak

The admonition was added because many references were not being made

so that means that I should list in the admonition only those functions that are not automatically turned into a link by sphinx?

the automatic references are indeed meant to show up this way

is this really useful?


If this is indeed the intended behavior then I think the documentation should be amended, shouldn't it?

Whether or not a function is mentioned here should be decided depending on if a mini-gallery link prominently helps to illustrate that function; e.g. mention matplotlib.pyplot.subplots only in examples that are about laying out subplots, not in every example that uses it.

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.

OK, so we can close this issue or should we wait for @timhoffm (who wrote the above mentioned paragraph in #19232) to weigh in?

What is linked and what not is determined by sphinx-gallery (see https://sphinx-gallery.github.io/stable/configuration.html#references-to-examples):

When documenting a given function/class, Sphinx-Gallery enables you to link to any examples that either:

1. Use the function/instantiate the class in the code.
2. Refer to that function/class using sphinx markup :func:/:class: in a documentation block.

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

So to summarize: I think the request here is reasonable, but would need action primarily in sphinx-gallery.