Change gallery building to use nbsphinx

[angus-g]

Fixes #201 (see https://cosima-recipes.readthedocs.io/en/update-nbsphinx/tutorials/Using_Explorer_tools.html). However, we'll need to change how thumbnails are specified for galleries by tagging the cells with nbsphinx-thumbnail (https://nbsphinx.readthedocs.io/en/0.8.12/gallery/cell-tag.html). That's potentially pretty disruptive (will cause conflicts to everybody working on an existing notebook), so maybe we should wait for a quieter time to do that?

See the WIP builds for this branch at: https://cosima-recipes.readthedocs.io/en/update-nbsphinx/

• fix static thumbnails (for tutorials), specified in conf.py
• images in rendered notebooks not appearing?
• fix dynamic thumbnails (for documented examples)
• add instructions for setting thumbnails to contributing guide
• fix warnings in notebooks

Notebook warnings

Warnings

From DocumentedExamples/Meridional_heat_transport.ipynb:

cosima-recipes/docs/documented_examples/Meridional_heat_transport.ipynb:70:
    WARNING: File not found: 'documented_examples/"../Tutorials/COSIMA_CookBook_Tutorial.ipynb"'

From DocumentedExamples/Surface_Water_Mass_Transformation.ipynb:

cosima-recipes/docs/documented_examples/Surface_Water_Mass_Transformation.ipynb::
    WARNING: Could not lex literal_block as "ipython3". Highlighting skipped.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[angus-g]

We need a link to the thumbnails for them to be copied over to the doctree to be usable in the gallery. Since this only really applies to the tutorials, maybe we can just find a good place to sneak the image in?

Solved by putting them in _static

[angus-g]

To get the original behaviour for defaulting thumbnails to the last image in a notebook, we'd need spatialaudio/nbsphinx#707 (or something similar) to land. At the moment I've pointed RTD to my branch which includes this change.

The way thumbnails are specified other than this default has also changed: either the image can go in docs/_static/thumbnails and a new entry goes in the nbsphinx_thumbnails key in docs/conf.py (see https://nbsphinx.readthedocs.io/en/latest/gallery/thumbnail-from-conf-py.html); or a cell can be tagged (https://nbsphinx.readthedocs.io/en/latest/gallery/cell-tag.html).

[aidanheerdegen]

Hey @angus-g, sorry I only just got around to checking this out. Looks good from my perspective.

[navidcy]

I see some conflicts here have risen in the Compare_SSH_model_obs.ipynb example.
I presume is the changes from # -> ##?

[angus-g]

I see some conflicts here have risen in the Compare_SSH_model_obs.ipynb example. I presume is the changes from # -> ##?

Yeah, that's fine, I can resolve that. I still need to put some docs together for managing thumbnails, and it would be nice for the upstream PR to work first. Other than that, it's probably getting to a quiet enough time to switch over to nbsphinx and get prettier rendered notebooks!

[navidcy]

Do that!

[navidcy]

and open a new PR to keep working :)

[angus-g]

@navidcy mind having a poke around the build https://cosima-recipes--206.org.readthedocs.build/en/206/ and seeing if there's anything obviously broken? Otherwise I think this is ready to merge!

[navidcy]

The explorer tutorial looks great! Merge!