Hmmm the Circle failure is quite odd and the test failure was because the backreferences file was a directory which I didn't know was allowed... would anyone have a minute to review this?

the Circle failure is quite odd

Sphinx does not give the nicest tracebacks. Have you tried make html in the doc dir of sphinx-gallery, then looking at the logs? You probably need to have encoding='utf8' somewhere...

the test failure was because the backreferences file was a directory

Have you looked at the structure it produces locally? My guess is that the backreferences files end up somewhere where some other files do (like auto_examples/whatever.py, hence having a directory plus some "stuff" inside it), so you can't assume everything in that dir is a backref .examples file or something...

Thanks @larsoner, that was really helpful, I think I figured it out!

I think this turned out really well!

You have to zoom in a bit since there are a lot of entries in some cases but I think super useful.

Unused API Entries — Python documentation.pdf

I'm not sure I handled graphviz importing and adding to the extensions in conf.py properly though so someone should double check that. Other than that though, I think ready to go!

From a quick look, code looks reasonable! But CIs are unhappy. Let me know when things are green or you need help interpreting

To demo this functionality, could you open a PR to MNE-Python demoing this functionality? You can tell CircleCI over there to use your branch in https://github.com/mne-tools/mne-python/blob/64dff6189215cbead61db81d6e6de811a05633e3/tools/circleci_dependencies.sh#L15

Hmmm, I'm getting this and similar warnings causing Circle to fail /home/circleci/project/doc/auto_examples/sg_api_usage.rst:17: WARNING: py:func reference target not found: numpy.ndarray. Clearly numpy.ndarray is a function and it's in the intersphinx mapping, anyone have any advice on how to fix this?

Clearly numpy.ndarray is a function and it's in the intersphinx mapping, anyone have any advice on how to fix this?

np.ndarray is a :class: not a :func:

Ah yeah that makes sense, it's warning for numpy.sin as well which I should double check but I'm pretty sure that one is a function. Is there a way to put the proper reference with just knowing the string? Maybe some kind of exec code? That seems a bit unideal though....

You could try :py:obj:, it might resolve to either of those

Ok now this seems like a bug with backreferences since it's trying to find numpy.RandomState when it was imported as np.random.RandomState so it should be numpy.random.RandomState in the backreferences examples file. I looked into it for a bit but it's quite complicated...

Ok there's two things I'm a bit stuck on: 1) The bug in the name resolving code (above) for numpy.random.RandomState and 2) how to remove modules that are not instantiated directly without removing classes (that also are camel case and share a root with their methods like modules share a root with their functions). Maybe if someone who wrote a bit of the name finding code could take a quick look, that might save a lot of time because the name finding is a bit dense.

Well I realized that modules should be lower case AND share a root with functions or classes in that module whereas classes should be camel case (and also share a root with their methods) so that fixes that. I'm not sure if the numpy.random.RandomState is symptomatic of a larger problem, although I would guess that it is but I just made an exception in this PR for now so that things pass.

Ok, much more readable I think! I counted leaves instead of displaying for the ununsed API entries and broke the used API entries into sub-graphs, it's also much faster.

Trying on MNE now...

Now we're getting somewhere that's pretty useful!

Unused API entries in mne examples:

Usage graph for Evoked:

Since the while section was made optional, I got rid of the details, I hope that's okay @larsoner. Let me know if you want to do it a different way.

Ok, this is good to merge by me

Thanks this is a great addition, quick review and mostly some doc nitpicks. I have not been following this closely so please excuse any comments that are not relevant/don't make sense.

Thanks, I think there were some great clarifications!

The artifact looks good https://output.circle-artifacts.com/output/job/b2109ab5-5b22-4fa9-b0fc-30657ae11c14/artifacts/0/rtd_html/configuration.html, this is good to go by me!

Thanks @alexrockhill and @larsoner !