Read The Docs won't build

[xylar]

Currently, we can't build the documentation on Read The Docs because our environment uses too much memory (they're pretty stingy but then again it's a free service). In the past, I really tried everything I could to slim things down. It might be worth letting go of the autogenerated API documentation (the only part that requires installing the code itself), which is less helpful in any case.

[xylar]

@mark-petersen, do you ever use the API docs?

@milenaveneziani, do you have thoughts?

[mark-petersen]

Do you mean you have trouble compiling this whole thing?
https://mpas-analysis.readthedocs.io/en/master/

It seems like a shame to lose the "autogenerated API documentation". You mean this part, right?
https://mpas-analysis.readthedocs.io/en/master/api.html#

The whole documentation site is such a nice interface. I was thinking we should switch over to this for MPAS-Model as well.

There must be a lot of other code repositories out there that are much larger than MPAS-Analysis that use readthedocs. I wonder what they do.

[xylar]

It's not about the size of the code repo. It's about how memory intensive it is to do the conda install <packages>. MPAS-Analysis has some pretty big dependencies in that regard and there's nothing we can really do about that.

This wouldn't affect MPAS-Model and we should definitely switch to Read the Docs or something similar. What we do now is horrid...

[bradyrx]

I had similar issues at climpred (https://climpred.readthedocs.io/en/stable/) when using nbsphinx to auto-run notebooks that utilized matplotlib/cartopy. I had to just pre-run the notebooks that used these packages before building the docs, so that it's just uploading the jupyter notebook and not actually trying to run it.

It's a shame, because we were using nbsphinx auto-run as a test on top of our testing suite. The memory they allocate is quite low.

FYI, one nice development is that they have a beta version for building readthedocs on PRs. See "getting started" here. I emailed them and within a day had readthedocs auto-building my PRs so you can test that they build properly.

[xylar]

I think I'm going to just switch to building the docs in Travis CI (actually I already did!) and uploading them to GitHub Pages instead of ReadTheDocs. You have to take care of a few things related to versioning yourself but mostly the benefits seem to out-weight the problems I keep running into on Read The Docs.

The lack of building in PRs has been one of the biggest headaches for me, so I'm glad to see that improvement is on the way but I think it's probably too little, too late for me and we're going to find another solution.