Investigate excessive resource use on ReadTheDocs and explore solutions

[erogluorhan]

Review our resource use with the ReadTheDocs builds (excluding the MPAS notebook's use as it will be moved to a Pythia cookbook soon as part of #524 ).

[kafitzgerald]

A few notes here:

We're almost certainly exceeding both the memory and run time limits for Read The Docs community: https://docs.readthedocs.io/en/stable/builds.html#build-resources

Apparently this was known and we requested some additional resources at one point, but now are exceeding those (and/or the limits were changed).

@anissa111 kindly pointed out that we can see the run times for each of the examples here: https://github.com/NCAR/geocat-examples/actions/runs/6332873280/job/17200094236#step:4:715

Our current docs failures seem be on the NCL_topo_1.py example (likely for exceeding memory usage). I profiled this quickly on my machine and it's taking a little over a minute and a half to run (mostly grabbing the data) and a significant amount of memory (plotting the elevation data) - greater than 6GB. This seems like a lot, but we're also plotting global elevation data at very high resolution (higher than the original NCL example - more recent versions don't have a 5deg option). I was curious what changing imshow to plot would do and it make the resource even higher (by quite a lot).

NCL_animate_1.py is also very resource intensive, but on my machine it takes less than 30s and less than 1GB of memory. Interestingly in CI this example takes much longer. Opting not to save the animation also cuts down on resource use some. See PR #538.

We could make these examples smaller, but I at least for the former it would probably add some code and move it away from replicating the NCL usage example.

I'm starting to wonder if it might make more sense to move off of ReadTheDocs instead for this and just use GitHub pages. That would eliminate some of the pressure to minimize resource use.

In short:

• The NCL_topo_1.py and NCL_animate_1.py scripts are both quite resources intensive. So unfortunately it's not just the notebook that's a problem.
• I think we should look into some options for non-RTD solutions and/or maybe we can do something with caching to help

[jukent]

#538 is merged, doesn't solve larger problem though

[jukent]

Pythia uses deploy previews with GitHub pages (one of the weaker points for GH pages), here is our GH action for that: https://github.com/ProjectPythia/projectpythia.github.io/blob/main/.github/workflows/trigger-preview.yaml

[kafitzgerald]

Between #538 and #557 we have a temporary fix in place. We also have a medium #564 and longer term plan #548 so I'm going to close this for now.