Fix RTD configuration

[amotl]

This is a followup patch to GH-142, incorporating some learnings from GH-139, and from coddingtonbear/python-measurement#77. Thank you, @codingjoe.

Other than some refactorings, the patch hopefully fixes the RTD build, by installing the libeccodes-dev and libgeos-dev distribution packages, in order to satisfy the installation of cartopy and friends.

[amotl]

I tried to re-run the RTD job three times, but it always runs into a timeout. Let's try later again.

ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.

-- https://readthedocs.org/projects/herbie/builds/19125416/

[amotl]

I've just submitted a support request to RTD.

---

Dear lovely Read the Docs team,

first things first, I wish you an excellent new year.

We are in the progress of adding the documentation of Herbie [1] to Read the Docs, but, after believing we got everything in place with [2], we are running into timeouts on the build process, like outlined at [3].

We can't make any sense of that, so we are humbly asking if you have any suggestions for us?

With kind regards,
Andreas.

[1] https://github.com/blaylockbk/Herbie
[2] #145
[3] https://readthedocs.org/projects/herbie/builds/19126011/

[blaylockbk]

Thanks for asking rtd support. Another dependency Herbie has that can't be installed with pure pip is cfgrib, which requires eccodes.

[blaylockbk]

This might help us...looks like rtd lets us specify a conda environment.
https://docs.readthedocs.io/en/stable/config-file/v2.html#conda

[amotl]

Hi Brian,

while I admit Conda is absolutely needed to keep ones sanity in non-Linux environments, Conda environments are not cheap to install ¹. Those CI jobs will happen to run so often that I believe it really makes a difference not wasting resources, and I think the same applies to our obligation to care about the resources at RTD. At GH-139, I've deliberately chosen to not use Conda to run the tests on a Linux environment, for the same reasons ².

With those dependencies, Herbie would install and run its test suite without issues on GHA.

Herbie/.github/workflows/tests-python.yml

Lines 57 to 60 in 899fb5f

	- name: Install prerequisites (Linux)
	if: runner.os == 'Linux'
	run: |
	sudo apt -y install libgeos-dev libeccodes-dev

With the most recent update to this patch, I've also added those dependencies to the RTD configuration.

Herbie/.readthedocs.yml

Lines 14 to 16 in 7394517

	apt_packages:
	- libeccodes-dev
	- libgeos-dev

With kind regards,
Andreas.

Footnotes

1. As excellent as Conda environments are, as expensive they are usually when setting them up on CI environments each and every time. And, yes, appropriate caching is not trivial. Those details usually do not matter too much on workstation's sandboxes, because one usually does not rebuild environments very often. But any kind of CI job, running so often, it will add up significantly, waste resources, and slow down development. ↩

2. I admit I did not go into the details of installing the wgrib2 program yet, because the test suite is currently skipping the corresponding tests. But I am sure there will be a way to install it "natively" on Linux, without needing to use Conda? ↩

[amotl]

Hi again. 3ffd4f7 may have improved the situation. [1] shows a successful build, and the HTML documentation can be inspected at [2].

[1] https://readthedocs.org/projects/herbie/builds/19130539/
[2] https://herbie--145.org.readthedocs.build/en/145/

[blaylockbk]

Wonderful! It's good to see the docs again. It sure was nice that I didn't have to build the docs myself. Thank you for tracking down the unexpected issues and figuring out how to address them. This really helps Herbie feel more "grown up".

Now I'll take a look at the other tasks you brought up 👍🏻

again, thank you!