search

spatialaudio / nbsphinx

:ledger: Sphinx source parser for Jupyter notebooks
https://nbsphinx.readthedocs.io/
MIT License
451 stars 130 forks source link

Sphinx-gallery style backreferences? #545

Closed StanczakDominik closed 2 years ago

StanczakDominik commented 3 years ago

Hi, I use nbsphinx in PlasmaPy, having transitioned to it from sphinx-gallery, and I'm really happy with it :) thanks for all your great work!

One thing I've been thinking about is sphinx-gallery style backreferences. As an example, take the documentation for skimage.measure.find_contours. If you scroll down, you see a dynamically generated list of all examples using that function. Note how this is not at all defined in the function's docstring itself.

My question is: has anyone thought about mirroring this functionality in nbsphxing? This appears to be its current implementation. I'd be happy to take on implementing this (while procrastinating other projects, as one does) given some feedback and pointers, if this is at all possible to do with nbsphinx. I imagine it might be tough, given that sphinx-gallery AFAIK runs its own execution model while nbsphinx, as I understand it, leverages existing notebook infrastructure.

mgeier commented 3 years ago

has anyone thought about mirroring this functionality in nbsphxing?

Yes, I've thought about it, but it looked like a lot of work ...

I was more interested in having links from certain words in the source code (in code cells) to the API docs (including external docs via sphinx.ext.intersphinx), but I guess the backreferences are using the same underlying data.

I'd be happy to take on implementing this (while procrastinating other projects, as one does) given some feedback and pointers, if this is at all possible to do with nbsphinx.

This would be great, but I think I cannot really give any pointers ... I don't know how this could be implemented.

I imagine it might be tough, given that sphinx-gallery AFAIK runs its own execution model while nbsphinx, as I understand it, leverages existing notebook infrastructure.

Yeah, I would definitely not implement the notebook execution as part of nbsphinx.

I think it would be best to implement this in https://github.com/jupyter/nbclient (which is used within nbconvert).

Ideally, this should not only work with Python, but with all supported languages.

I guess this might also require some extensions to the Jupyter kernel protocol?

Some more links:

https://github.com/jupyter/nbconvert/issues/1155

https://github.com/anntzer/sphinx-exhibit

mgeier commented 2 years ago

In the meantime, a new sphinx extension has come to light: https://github.com/felix-hilden/sphinx-codeautolink/

This creates links from code cells to the documentation (which is already enabled in the nbsphinx docs), and it can also create backlinks (which is not enabled in the nbsphinx docs). See https://sphinx-codeautolink.readthedocs.io/en/latest/examples.html.

I don't know if it would be feasible to extend the backlinks feature to include gallery-like thumbnails.

StanczakDominik commented 2 years ago

Yeah, I've heard about it, and come to think of it I'm pretty sure it fully solves my use case here at least! I'm going to close this one. Thanks for the reminder!