Documentation page is blank

[agjohnson]

This is an issue that we are tracking and working on a fix for. I wanted to give an issue that is publicly tracked, as so far most of our discussion on this bug has been on internal issues.

Problem

Some documentation pages appear blank, starting last week on Oct 8th. These pages are usually large pages or ipynb notebooks that output images inline, and so have a large page response.

The technical issue is that our response transformation that we use in our workers is not correctly handling the large response, emitting an exception, and then returning no content.

Fixes

There are two fixes, we're working to get at least something out shortly:

• Return the original response body unaltered. This effectively removes Addons for the page however.
• Parse the response in a way that never triggers an exception. This might be harder or would require a rewrite of some of the worker logic.

Temporarily, if you are hitting this error you can ~~either disable Addons for your project or~~ try to reduce the response size for the page. If you are using a notebook, you could try to output image as files instead of using inline data in the HTML for the images.

Edit: disabling Addons does not avoid the bug

We'll update here with more information once we have a final fix.

[sammlapp]

Temporarily, if you are hitting this error you can either disable Addons for your project or try to reduce the response size for the page. If you are using a notebook, you could try to output image as files instead of using inline data in the HTML for the images.

Thank you for providing a workaround. For those using nbsphinx to generate notebooks, is there a setting that would use image files rather than inline HTML for images in notebook cell outputs?

[sammlapp]

Disabling add-ons and rebuilding did not resolve the issue for me

[agjohnson]

Hrm, this is a little confusing as disabling should avoid the injection logic, but I might be missing something here. Thanks for the update either way, it's good to know that works.

For those using nbsphinx to generate notebooks, is there a setting that would use image files rather than inline HTML for images in notebook cell outputs?

I would be surprised if there wasn't an option for this, but I don't frequently use notebooks or nbsphinx. Maybe someone with more experience has an easy answer here though.

[sammlapp]

Hrm, this is a little confusing as disabling should avoid the injection logic, but I might be missing something here. Thanks for the update either way, it's good to know that works.

To be more specific, the option to totally disable all Addons is greyed out / unclickable for my project. I instead unchecked all of the individual checkboxes for each Addon, then re-built, and got the same blank page behavior.

[agjohnson]

I am currently testing out some fixes to our injection, including a temporary fix for this bug. If you are hitting this and would like to test, note your project URL/name and I'll add it to the test worker.

[AhmetNSimsek]

I am currently testing out some fixes to our injection, including a temporary fix for this bug. If you are hitting this and would like to test, note your project URL/name and I'll add it to the test worker.

Thanks @agjohnson! Could you please add siibra-python?

[sammlapp]

I am currently testing out some fixes to our injection, including a temporary fix for this bug. If you are hitting this and would like to test, note your project URL/name and I'll add it to the test worker.

https://readthedocs.org/projects/opensoundscape/ in particular this particular page: https://opensoundscape.org/en/latest/tutorials/audio.html

[agjohnson]

@AhmetNSimsek @sammlapp Added!

I have a little more background on what is actually happening here and I'm a bit surprised.

So, this is not just large responses that are triggering this. I can generate a 10MB file from /dev/random and it send through the worker fine.

But if I take one of the pages here at is triggering this and try to serve that even through a basic worker I do get a memory limit error, right on the line that a big inline data: URL is included on. I even get a segfault in vim on this line. If I send the same file as text/plain, the error goes away again.

I tried this on a basic in/out worker (no manipulation, just stream the response), and a streaming API worker.

So, it seems to me like the worker is implicitly processing the inline data URL during streaming of HTML files, which is news to me.

I've opened https://github.com/cloudflare/workerd/issues/2998

• https://github.com/cloudflare/workerd/issues/2998

[sammlapp]

Interesting, thanks for looking into this. From my perspective (I maintain a package and documentation, which includes notebook tutorials), figuring out how to have the notebooks build to HTML in a way that uses image files rather than in-line images seems like a reasonable approach. However, I haven't found any documentation of nbsphinx that suggests this is possible/currently supported.

[AhmetNSimsek]

Thank you @agjohnson for investigating it. @sammlapp , we use sphinx-gallery for creating tutorials and have the same issue. If I find a workaround, I'll share it here.

[sammlapp]

Thanks for working on this. Would we expect a fresh build of documentation to work now, only once there is a new readthedocs release including the merged PR?

[agjohnson]

So I just got done deploy the final changes and every project should at least now avoid an exception. There is still some debugging that needs to happen to determine what is happening with the data urls, and getting an actual fix there. But at least for now, without rebuilding or other intervention, all project pages should load -- albeit without any addons injected.