intersphinx/sphinx-hoverref

[zmoon]

For easier and more robust links to the xarray documentation.

Jupyter Book uses it in their own docs, so it is definitely possible. I guess the downside is that the notebook would look more messy in Jupyter. But maybe sphinx-codeautolink would work, at least for the code blocks.

[scottyhq]

Nice idea @zmoon this would definitely be interesting to try! We're in the midst of a pretty big revamp leading up to a scipy workshop in July, and just switched to jupyterbook so there is a fair amount in flux at the moment.

[zmoon]

What do you think about intersphinx references in the text? Would be nice to have the links, and reduced maintenance vs manually putting the links in, though for people running the notebooks in Jupyter the texts becomes a bit uglier.

[scottyhq]

I agree think the major drawback of Jupyter Book right now is the discrepancy between rendered notebooks on the website with lots of extra formatting compared to what is possible in Jupyter Lab. Numpy tutorials require only using CommonMark in notebook cells for this reason (https://github.com/numpy/numpy-tutorials#contributing)

My hunch is that the primary mode for consuming this material is on the website rather than Jupyter Lab, except for the case of workshops where everyone is on Jupyter Lab. And during workshops, the focus is on code cells (people can have the website open in another tab for the rendered version).

So I'm in favor of anything that makes for easier navigation on the website. Yet another convenience could be adding https://sphinx-hoverxref.readthedocs.io/en/latest/ https://blog.readthedocs.com/hoverxref-intersphinx.

[dcherian]

FWIW scikit-image does this very well with underlined links making it clear what you can click on: https://scikit-image.org/docs/stable/auto_examples/segmentation/plot_regionprops.html

[zmoon]

scikit-image does this very well with underlined links

Sphinx-Gallery