notebook: [DOCS] Notebook examples not rendering properly

Description

Between version v5.7.6 and the stable, the notebook examples section has become broken. For example:

The working version on v5.7.6

The broken version on stable

It looks like the notebook .ipynb files are being parsed as raw text, rather than parsed properly by nbsphinx.

I tried getting a dev environment set up to debug this, but pip install . wasn’t working because I ran into the error error: [Errno 2] No such file or directory: 'bower'. So opening this issue to track it.

The notebook examples are at the link below, and I suspect the fix will need to be somewhere around there, or in the Sphinx configuration:

https://github.com/jupyter/notebook/tree/master/docs/source/examples/Notebook

Originally reported in https://discourse.jupyter.org/t/error-in-jupyter-readthedocs-page-rendering/11038

About this issue

Original URL
State: closed
Created 3 years ago
Comments: 24 (24 by maintainers)

Most upvoted comments

yahoo! it works now 😃

choldgraf on Oct 11, 2021

Sorry, I didn’t realize that you are using conda on RTD. I’m normally not using it because it’s soooo much slower.

mgeier on Oct 11, 2021

@kevin-bates OK I think I’ve deleted one of the webhooks so we should only get one build per merge instead of two…we can re-sync it if the builds are broken somehow.

I’ve also triggered another build on master to see if the environment has updated

choldgraf on Oct 11, 2021

No problem, I love to help!

Just as an explanation: Since https://github.com/spatialaudio/nbsphinx/pull/578, .ipynb files are not registered if they are already in source_suffix. And if they are, that’s actually wrong (at least according to modern Sphinx practices), see https://github.com/spatialaudio/nbsphinx/issues/595#issuecomment-902148464.

mgeier on Oct 11, 2021

Thanks @choldgraf - that’s the right thing to do.

I’m unable to reproduce this locally or via CI. Even the RTD build in the PR was successful: https://jupyter-notebook--6194.org.readthedocs.build/en/6194/.

Looking at the raw RTD logs for the most recent failure vs. the most recent success I see that the only “version difference” in the installed packages is nbshpinx- 0.8.6 for the failing case and 0.8.7 for the successful case!

This implies that the changes in #6194 to pin nbshpinx to 0.8.6 were a red herring. Moreover, looking for assert ‘Verbatim’ in lines[0] leads to this issue in sphinx - https://github.com/sphinx-doc/sphinx/issues/9458 which points at this issue in nbsphinx: https://github.com/spatialaudio/nbsphinx/issues/584 - which was addressed in 0.8.7 😄.

Therefore, since the 0.8.6 theory was invalid, it seems we should revert #6194. However, before doing that, I think it would be good to get a sphinx doc expert and, since I’ve seen Matthias on other issues, I think it would be good to see if @mgeier has any ideas.

kevin-bates on Oct 11, 2021