Test first_notebook_cell

[banesullivan]

Would it be possible to run first_notebook_cell when running each of the examples to test that the contents are valid?

I imagine having Jupyter magic like %matplotlib inline might be a problem when executing examples in the test environment, but perhaps there is a way in which we could verify the code in first_notebook_cell such that projects aren't shipping broken examples like what happened in https://github.com/pyvista/pyvista/issues/1711

[larsoner]

I think a run_first_notebook_cell = False (by default, for backward compat) makes sense, where True would run any lines that don't start with %.

[MatthewFlamm]

Am I understanding that first_notebook_cell isn't actual run per example when generating the documentation? It is only added when users download the notebook? This isn't clear to me in the documentation https://sphinx-gallery.github.io/stable/configuration.html#add-your-own-first-and-last-notebook-cell. This seems to be true in my testing, but I wanted to confirm it.

If this interpretation is correct, I will open another feature request for having setup and teardown sections that are run when generating the documentation but not when downloading the example. This is the mirror functionality to first_notebook_cell and last_notebook_cell. This is useful when there is code that is modifying global settings in an example like in the aforementioned https://github.com/pyvista/pyvista/issues/1711, and we want to make sure that these settings do not leak out of the example when an error is raised.

[larsoner]

Am I understanding that first_notebook_cell isn't actual run per example when generating the documentation? It is only added when users download the notebook?

Correct

I will open another feature request for having setup and teardown sections that are run when generating the documentation but not when downloading the example

We have https://sphinx-gallery.github.io/stable/configuration.html#reset-modules which might or might not do what you want already

[MatthewFlamm]

Thanks! This is a great pointer. I will consider adding some "See Also" language to the documentation as it would have helped me digest these options. I think there are still edge cases where this may not work. I will raise another issue, since I think my question is resolved in practice.

[lucyleeow]

Closing, continued in #866

[MatthewFlamm]

Sorry ~~if~~ that I made this more complicated in my questions inside this issue. I think the issue in #866 is separate from the request here.