[DOCS] Notebook examples not rendering properly

[choldgraf]

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

[kevin-bates]

Thanks for opening this issue @choldgraf.

I have managed to reproduce this following the same commands found in the readthedocs builds tab.. In comparing environments and docs-specific versions, there were few differences. Sphinx was 4.1.2 vs. 4.2.0 on the working and failing environments and nbsphinx was 0.8.6 vs 0.8.7 (working to failing). Turns out that this issue is a function of nbsphinx 0.8.7.

I've also noticed a couple of other anomalies wrt the doc builds that could probably be cleaned up.

I'll go ahead and submit a PR that pins nbsphinx to 0.8.6 for now - primarily out of ignorance and the fact that this may hopefully get us going again. If anyone has ideas as to what might be going on, please chime in. Looking at the nbsphinx release history, 0.8.7 consists of a handful of commits. Since I'm unfamiliar with Sphinx and notebook rendering, I'm not sure what help I can be in terms of a more final solution.

@blink1073 - could you please add me to the readthedocs maintainers?

[choldgraf]

Do you think it'd be helpful to do a quick update on the notebook docs to make them more maintainable, and point others in the right direction for other docs resources? I'd be happy to have a quick chat and brainstorm some low-hanging-fruit PRs with you

[blink1073]

I added kevin-bates to the list of maintainers.

[kevin-bates]

I added kevin-bates to the list of maintainers.

Thank you Steve.

Do you think it'd be helpful to do a quick update on the notebook docs to make them more maintainable, and point others in the right direction for other docs resources? I'd be happy to have a quick chat and brainstorm some low-hanging-fruit PRs with you

Yes - that would be great. Please feel free to provide PRs. Also, we have a notebook dev meeting every Wednesday at 8:30 PDT on the Jupyter zoom (just prior to the weekly Lab dev meeting). I know it's late notice to join us today, but perhaps next Wednesday? Also, feel free to reach out to me on my GH email and we can set up a quick chat.

cc: @Zsailer

[Zsailer]

Do you think it'd be helpful to do a quick update on the notebook docs to make them more maintainable

@choldgraf, YES! Big resounding YES! 🤣

I think this would be extremely helpful moving forward. Anything we can do to lessen the maintenance needs on the project would be extremely helpful. I'm happy to hop on a call anytime.

[choldgraf]

@Zsailer wanna find a quick time to chat about this in the next few days? I am happy to just pick a time and post a jitsi link as well in case others would like to chat. My schedule is pretty free, esp during nap times 😅

I think for me, the goals for this would be to

• boost maintainability
• reflect the current state of development and strategy for the interface
• direct people to other documentation and projects in the ecosystem

That kinda thing

[choldgraf]

Reopening because the Sphinx build is failing :-(

link to sphinx build

Here's the exception:

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/jupyter-notebook/conda/master/lib/python3.8/site-packages/nbsphinx.py", line 2151, in depart_codearea_latex
    assert 'Verbatim' in lines[0]

[kevin-bates]

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 - sphinx-doc/sphinx#9458 which points at this issue in nbsphinx: spatialaudio/nbsphinx#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]

@mgeier - thank you for looking into this (and so quickly!!) - it's much appreciated!

[mgeier]

No problem, I love to help!

Just as an explanation: Since spatialaudio/nbsphinx#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 spatialaudio/nbsphinx#595 (comment).

[choldgraf]

@kevin-bates and @mgeier HUGE HUGE THANKS for helping sort this one out again :-)

[kevin-bates]

@mgeier - I have a couple of questions for you...

1. Do you happen to know why the PR RTD build passes, but not the "branch/tag-based builds": https://readthedocs.org/projects/jupyter-notebook/builds/. Is there a timeframe between merge and these builds since it appears they're failing with the "Verbatim" assertion (and still using nbsphinx 0.8.6)?
2. Do you know what leads to the "Duplicated build" failures we see immediately following other (successful or failing) builds?

[choldgraf]

If somebody makes me an admin on the readthedocs site i can also try to debug

[kevin-bates]

I'd be happy to - is your RTD account name choldgraf?

(Looks that way - confirmed after adding. 😄 )

[choldgraf]

@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]

Looking again at the build logs, I think that the issue here is that the build failure is on the latex generation build. The HTML build works just fine, but the latex generation build is causing the problem:

https://readthedocs.org/projects/jupyter-notebook/builds/14965870/

I suspect that we don't get errors in the PR previews because they only generate HTML assets, not pdf/latex as well.

I'm re-opening this because it's still an issue until we fix those Latex builds. Is anybody opposed to simply configuring ReadTheDocs not to build PDFs of the docs? I think this would affect some readers, but probably not as many as having all of the example notebooks non-functional.

[mgeier]

The "Verbatim" problem is happening when using Sphinx >= 4.1.0 AND nbsphinx < 0.8.7.
See spatialaudio/nbsphinx#591.

That's why I removed the nbsphinx version pinning in #6200.

[mgeier]

I suspect that we don't get errors in the PR previews because they only generate HTML assets, not pdf/latex as well.

Yeah, that's a pity (but understandable, because it would cause a significant additional load on RTD).

I would recommend to add a PDF build to CI (using Github Actions or CircleCI or whatever) to check the PDF build on each PR.

Is anybody opposed to simply configuring ReadTheDocs not to build PDFs of the docs?

LaTeX/PDF support is already underrepresented, so it would be really nice to keep it.

I've invested significant effort in keeping LaTeX/PDF support working in nbsphinx (with the help of others, of course), so notebook support shouldn't be the reason to stop building PDFs.
Of course there are limits, but I think it's OK if certain features don't work in PDFs, but they shouldn't break the entire build.

[choldgraf]

@mgeier hmmm so what is the fix here? Pin to Sphinx <4.1 until a patch is released in nbsphinx that lets us bump the version back up?

[kevin-bates]

Sigh - yeah, I'm seeing nbsphinx 0.8.6 references and they're probably interfering with this portion of the build. I should have caught this when reviewing #6200, but there was still a pin to 0.8.6 in docs/environment.yml.

PR submitted: #6201

[kevin-bates]

crossed posts: @choldgraf - let's see where #6201 leaves us first.

[mgeier]

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

[choldgraf]

yahoo! it works now :-)

[choldgraf]

Many thanks @kevin-bates and @mgeier for quick turnarounds this latest round of fixes 🙂