Let readthedocs build the documentation environment based on env_climada.yml (#687)

* Use env_climada.yml as environment in readthedocs

Remove requirements/env_docs.yml

* Fix wrong path in doc/README.md

* Add note on the removal of requirements/env_docs.yml

* Try installing additional packages in readthedocs environment

* Try not specifying the readthedocs environment name

* Remove custom package installation from RTD config

* Fix Python version in RTD build process

* Update CHANGELOG.md

---------

Co-authored-by: emanuel-schmid <[email protected]>

Author: peanutfun

.readthedocs.yml

@@ -5,8 +5,13 @@ build:
   tools:
     python: "mambaforge-4.10"
 
+  # Append fixed Python version to requirements
+  jobs:
+    pre_create_environment:
+      - echo "  - python=3.9" >> requirements/env_climada.yml
+
 conda:
-  environment: requirements/env_docs.yml
+  environment: requirements/env_climada.yml
 
 python:
   install:

CHANGELOG.md

@@ -67,6 +67,7 @@ Code freeze date: YYYY-MM-DD
 - climada.hazard.centroids.centr.Centroids.values_from_raster_files
 - climada.hazard.centroids.centr.Centroids.values_from_vector_files
 - climada.hazard.centroids.centr.generate_nat_earth_centroids
+- `requirements/env_docs.yml`. The regular environment specs are now used to build the online documentation [#687](https://github.com/CLIMADA-project/climada_python/pull/687)
 
 ## 4.1.1
 

doc/README.md

@@ -29,15 +29,18 @@ Next, execute `make` (this might take a while when executed for the first time)
 make html
 ```
 
-The documentation will be placed in `doc/_html`. Simply open the page `doc/_html/index.html` with your browser.
+The documentation will be placed in `doc/_build/html`. Simply open the page `doc/_build/html/index.html` with your browser.
 
 ## Updating the Documentation Environment for Readthedocs.org
 
 The online documentation is built by [`readthedocs.org`](https://readthedocs.org/).
-Their servers have a limited capacity, which is typically exceeded by Anaconda when it tries to resolve all dependencies for CLIMADA.
-We therefore provide a dedicated environment with *fixed* package versions in `requirements/env_docs.yml`.
+Their servers have a limited capacity.
+In the past, this capacity was exceeded by Anaconda when it tried to resolve all dependencies for CLIMADA.
+We therefore provided a dedicated environment with *fixed* package versions in `requirements/env_docs.yml`.
+As of commit `8c66d8e4a4c93225e3a337d8ad69ab09b48278e3`, this environment was removed and the online documentation environment is built using the specs in `requirements/env_climada.yml`.
+If this should fail in the future, revert the changes by `8c66d8e4a4c93225e3a337d8ad69ab09b48278e3` and update the environment specs in `requirements/env_docs.yml` with the following instructions.
 
-For re-creating this environment, we provide a Dockerfile.
+For re-creating the documentation environment, we provide a Dockerfile.
 You can use it to build a new environment and extract the exact versions from it.
 This might be necessary when we upgrade to a new version of Python, or when dependencies are updated.
 **NOTE:** Your machine must be able to run/virtualize an AMD64 OS.