Alternative to readthedocs for long doc builds

#1

Hi,

I remember that this problem was faced by many in this community, and I wonder if a solution was suggested to this problem.

ReadTheDocs is great, but not adapted to long runs (and also does not support containerized environments). I know how to build a documentation locally and host it (that’s how I do it for https://oggm.org/tutorials), but the feature I am missing the most from readthedocs is the possibility to store various versions of the docs and switch between them.

Does someone in this community have a recommendation or pointers on how to handle expensive documentation builds?

Thanks!

Fabien

#2

For Datashader.org what we did is divide and conquer. We had previously included lots of domain-specific examples in the Datashader docs, each with their own environments and dependencies, and in the end it became impossible to build the docs on readthedocs or through our own CI systems; timeouts all the time! We solved it by splitting our docs into the actual docs, all using one shared enviornment, and then a separate site examples.pyviz.org that hosts individual examples, each built separately when it’s updated and then never rebuilt until that one changes. That way when we make a change to Datashader, we don’t have to rebuild all the examples, just the actual (lean) docs. This approach has been working well for us, at least!

3 Likes
#3

Thanks @jbednar ! This makes a lot of sense.