OpenGL and rendered documentation

[behackl]

The Problem

From looking at the docker image used by Readthedocs for building the documentation (https://github.com/readthedocs/readthedocs-docker-images/blob/master/Dockerfile) it seems like a bunch of requirements needed in order to run the OpenGL renderer are missing.

While we were able to find a workaround for ffmpeg (installing a python package which includes a prebuilt version of ffmpeg in its wheel), I am not so confident that we are able to do something similar here: installing system packages actually isn't supported by RTD.

This is a problem, as it means we won't be able to render our own video snippets for the documentation while building it as soon as we switch to OpenGL as the default renderer.

Potential Solutions

I've thought about some different ways forwards, but right now I'm not sure that any of these are really easily doable.

• Remove rendered videos from the documentation. (Not great, big oof.)
• Host our own version of RTD which runs with a modified docker image. (Requires some space where it can be hosted + the corresponding devops work.)
• Build a webservice able to render manim snippets, make RTD use that service instead of rendering the videos locally. (We need some space to host the service, and I feel that would be more complicated to setup than hosting RTD.)
• Variation: use a GH action to render examples, then deploy them to some static webserver. Let RTD simply link to there. (Probably difficult to get it right, but otherwise a more or less clean solution. Also needs hosting space.)
• Try to find a workaround that allows installing system packages in RTD. (And hope they won't mind.)
• Switch from RTD to GH pages, try to setup everything via actions. (Might be possible, but having multiple different documentation versions might be not possible or might prove to be very difficult.)

Further ideas and suggestions are more than welcome.

[naveen521kk]

I have hit the same situation with ManimPango but later found that the RTD supports Conda and I could build ManimPango there easily, as Pango is built and maintained by Conda Forge, https://anaconda.org/conda-forge/pango. That simply solved the problem for me, is the same applies to the present situation?

Remove rendered videos from the documentation. (Not great, big oof.)

I don't want that to happen.

Host our own version of RTD which runs with a modified docker image. (Requires some space where it can be hosted + the corresponding devops work.)

This requires a lot of work though, also we don't have access to those places where this can be done.

Build a webservice able to render manim snippets, make RTD use that service instead of rendering the videos locally. (We need some space to host the service, and I feel that would be more complicated to setup than hosting RTD.)

Same as previous, should be a lot of work and we don't have access to them.

Variation: use a GH action to render examples, then deploy them to some static webserver. Let RTD simply link to there. (Probably difficult to get it right, but otherwise a more or less clean solution. Also needs hosting space.)

Using GH actions can be done always, they offer it for free. I think a small server can do, and after that, we can contact JSdelivr(we previously did), and use it as a CDN. But still, it would be a hassle, but if manim_directrix should be able to handle it correctly, this would be a potential solution.

Try to find a workaround that allows installing system packages in RTD. (And hope they won't mind.)

No idea how that's gonna work.

Switch from RTD to GH pages, try to setup everything via actions. (Might be possible, but having multiple different documentation versions might be not possible or might prove to be very difficult.)

I think that's what is done by projects like NumPy, we can try doing so. Requires a lot of work and is only a last option.

[Darylgolden]

readthedocs/readthedocs.org#8065 Could this be the solution to our woes?

[behackl]

The RTD feature adding support for installing system packages via apt has just been merged and should be available soon ("should be live on next Tuesday").

We'll have to investigate whether we can get opengl rendering to work then -- I'm sure that it will certainly bring us a lot closer.

[CountingBeeps]

Well, it's a bit after next Tuesday now :) Any progress here?