API gallery generator should be based on function call not on the import. But we have still to debug it as not all functions are always recognized. Some early issues of this are #70 and #113 and we have not found the time to get to solve them.
The code for the API gallery should be isolated in sphinx-gallery/back_references.py
I feel is not a very good idea to have the comments in the example file to generate the API pages, the main goal of the gallery is transform from good code to nice HTML and adding extra stuff to the comments to control the gallery behaviour is not good. I think is best to try to figure out how to catch all functions and objects used in the file.

I think that's a fair point - agreed that it's a pretty suboptimal solution to have more comments in the rendered HTML. Maybe better to see what other solutions will come about for catching function calls etc, and then I'll try to figure out ways to solve this problem in the future. I'll close the issue unless any other folks wanna weigh in

I think is best to try to figure out how to catch all functions and objects used in the file.

I agree in principle. However in the MNE case we have a lot of classes that get returned by functions and then get used extensively, but are rarely created or imported manually by the user. So for SG to get this right, it would need to do something like parse the docstring (assuming it's e.g. NumPy-formatted) to try to get the return object type. This sounds quite hard to get right...

I feel is not a very good idea to have the comments in the example file to generate the API pages

Right now the code in the example file is used to generate the API pages (by way of the backrefs). The proposal is to also allow some comments to do it, too. I don't see these as being so different, really...?

Maybe a compromise would be to parse the non-code for statements in the that contain Sphinx references, like:

This example makes use of :class:`mne.SourceEstimate`.

Then it's clean RST format, and should/could link nicely?

I guess a challenge there could be that someone might reference other classes etc that are worth linking but not necessarily worth including in the gallery below. Not sure how common this would be, but if it weren't that common it might be a good compromise. Alternatively I guess there could be a :gallery: RST directive or something.

I guess a challenge there could be that someone might reference other classes etc that are worth linking but not necessarily worth including in the gallery below.

I imagine we can work around this. Parse for Python refs, and see if the current module being documented (e.g., mne) has the necessary page.

Oh wait I misinterpreted what you said. I think that would be rare enough not to worry about. -1 on adding a new directive, let's assume YAGNI.

We could at least offer the option to disable this behavior entirely.

Cool - the new directive is an extreme solution I agree

@Titan-C any comment on this starting here? This is a feature we still miss.

I agree w/ @Eric89GXL - Matplotlib would also have a huge benefit from improvements along these lines (e.g. SG isn't detecting any of the methods called on Axes objects that are created with plt.subplots)