fix: rendering of gif images in ipynb build

[m-reuter]

Rendering a gif image (in my case an animated gif) does not work.
The ipynb cell has:
display(Image(filename=outpath_gif))
which works in ipynb, but sphinx degrades to a text/plain representation and does not show the gif.

I applied a monkeypatch via conf.py in here:

Deep-MI/WhipperSnapPy#59

• Our tutorial notebook saves the rotation GIF to a temp file.
• We add Sphinx conf.py monkeypatches to include image/gif in nbsphinx output selection and rendering.
• We patch nbconvert’s output extraction so image/gif gets written as binary bytes to extracted files.

This works nicely and the animated gif shows in our tutorial:
https://deep-mi.org/WhipperSnapPy/dev/tutorials/whippersnappy_tutorial.html
(last cell)

It would be nice if this can be added to nbsphinx directly to avoid the monkey patch, which is not future proof.

(see also spatialaudio/nbsphinx#864 for the same issue posted in npshinx as both projects need updates for this to work).

[yogitha-star]

Hi! I’d like to work on this if that’s okay. I’ll try to reproduce the issue and look into how image/gif is handled.

[m-reuter]

Hi @yogitha-star that's great. Look at my PR #2271 , which should already be enough to support gif. I could not test it fully yet.

[yogitha-star]

Tested test_gif.ipynb. GIF shows correctly in Jupyter Notebook, but in the HTML exported via nbconvert it does not animate. Did not make any changes, only tested as requested

[m-reuter]

Sorry, I had missed a few places. I updated the PR and it should work now (worked for me locally). Can you test again. Thanks.

[m-reuter]

Hi @yogitha-star , can you take a look again, should work now. Thanks.

[yogitha-star]

Hi @m-reuter,

I tested the updated changes again.

Steps I followed:

Created a notebook with Image("test.gif").

Verified that the GIF animates correctly in Jupyter Notebook.

Exported the notebook using jupyter nbconvert --to html.

Result:
The GIF displays correctly in the notebook, but in the generated HTML it still does not animate on my side.

[m-reuter]

demo_gif_html.py

test_gif_demo.ipynb

Here is a small working example. Just run demo_gif_html.py to load the ipynb and convert it to html. Open the created demo_gif_output.html in a browser and the animated gif should play. Works for me.

Very likely when you run jupyter nbconvert it uses the system nbconvert which might come before the local one in your path. That one does not have the gif support, so it fails. For me it worked with the PR version also with the Jupyter command when I uninstall the system one and install the patched one.

Also sometimes a different python version is used (with its own system-installed templates, missing the image/gif support). You can install the repo in editable mode for your specific python, eg.:

/usr/local/bin/pip3.11 install -e .

when testing changes from a checked-out branch, make sure the repo is installed in editable mode for the same Python interpreter that the jupyter CLI uses. You can verify with:

head -1 $(which jupyter-nbconvert)   # shows the interpreter
/that/python -c "import nbconvert; print(nbconvert.__file__)"  # should point into the repo