The online documentation is automatically built when the
develop branch are updated.
Additionally, documentation previews will be built for every pull request on GitHub, and will be displayed under “Checks”.
Note that the online documentation allows you to switch versions.
By default, you will see the
stable version, which refers to the latest release.
You can switch to
latest, which refers to the latest version of the
You can also build and browse the documentation on your machine. This can be useful if you want to access the documentation of a particular feature branch or to check your updates to the documentation.
For building the documentation, you need to follow the advanced installation instructions. Make sure to install the developer requirements as well.
Then, activate the
climada_env and navigate to the
conda activate climada_env cd climada_python/doc
make (this might take a while when executed for the first time)
The documentation will be placed in
doc/_html. Simply open the page
doc/_html/index.html with your browser.
Updating the Documentation Environment for Readthedocs.org#
The online documentation is built by
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
For re-creating this 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.
Follow these instructions:
Install Docker on your machine.
Enter the top-level directory of the CLIMADA repository with your shell:
Instruct Docker to build an image from the
docker build -f doc/create_env_doc.dockerfile -t climada_env_doc ./
Run a container from this image:
docker run -it climada_env_doc
You have now entered the container. Activate the conda environment and export its specs:
conda activate climada_doc conda env export
Copy and paste the shell output of the last command into the
requirements/env_docs.ymlfile in the CLIMADA repository, overwriting all its contents.