Let readthedocs build the documentation environment based on env_climada.yml

[peanutfun]

Changes proposed in this PR:

• Remove requirements/env_docs.yml
• Use requirements/env_climada.yml for building the docs. This will take a bit longer because the dependency solver actually has to resolve the environment.
• Add notes on how to revert these changes in the future in case something goes wrong.

This PR fixes #654

PR Author Checklist

• Read the Contribution Guide
• Correct target branch selected (if unsure, select develop)
• Descriptive pull request title added
• Source branch up-to-date with target branch
• Documentation updated
• [ ] Tests updated
• Tests passing
• No new linter issues
• Changelog updated

PR Reviewer Checklist

• Read the Contribution Guide
• CLIMADA Reviewer Checklist passed
• Tests passing
• No new linter issues

[emanuel-schmid]

@peanutfun do you know why the Read the Docs build failed?

[peanutfun]

Yes, I am trying to install the additional dependencies in the post-install step of the readthedocs build, but the environment is not named climada_env. I will give this another try but I do not want to dig any deeper. To make this cleaner, we would need to join the env_climada.yml and env_developer.yml into a single file

[peanutfun]

The readthedocs build now takes 6 minutes, about the time of the unit tests. So I think the longer duration is no issue at this point.

[peanutfun]

@chahank @emanuel-schmid This is working! We can ditch env_docs.yml and always build the documentation in an up-to-date environment.

[peanutfun]

@emanuel-schmid I recall you were a bit opposed to the idea of having a "flexible" environment for the docs (right?). I would be happy about your approval as well before merging! 🙏

[emanuel-schmid]

🤷 Neither I'm I opposed to the idea of a flexible environment nor am I keen on keeping yet another yml file up to date. It's just that we didn't introduce the env_docs.yml file for the sheer fun of it. Back then, it solved a problem that came up as a surprise, caused by the the straw that breaks the camel's back so to say. At the very moment the problem is not present anymore but there is no guarantee that it won't re-appear one day.

In principle, I'm happy to merge this PR nevertheless: when the problems comes back we still can solve it in the same manner.

But - right now, the PR doesn't solve a present problem and while we wait with merging we save about 5 minutes of cpu time with each commit on any PR branch and whenever a PR is merged.
Can't we just wait then until the current env_docs.yml file eventually causes a problem? It certainly will. 😉

[peanutfun]

@emanuel-schmid I don't think I agree. For now, there is no apparent problem, but the documentation will break as soon as a branch, e.g., adds a dependency. This PR avoids such issues in the future. Additionally, the build time does not suffer much. The last RTD build on this branch took 575s against 517s on the latest develop build.

Anyway, the approach is somewhat appealing. We can merge this when something with the docs breaks. However, we might then have to re-review this PR.

[emanuel-schmid]

the documentation will break as soon as a branch, e.g., adds a dependency.

👍

The last RTD build on this branch took 575s against 517s on the latest develop build.

Yes, but unlike the PR builds the develop build does the latex/pdf stuff too on RTD. PR builds take something between 350s and 400s

However, we might then have to re-review this PR.

I'll take that upon me. 😁

[peanutfun]

Very good. Then let's go with your approach and merge (only) as soon as something breaks 🙌

[peanutfun]

I'm glad this finally became useful 😇