# CLIMADA Documentation

The CLIMADA documentation consists of ``.rst`` files and [Jupyter](https://jupyter.org/) Notebooks.
It is built into an HTML webpage by the [Sphinx](https://www.sphinx-doc.org/en/master/index.html) package.

The [online documentation](https://climada-python.readthedocs.io/en/stable/) is automatically built when the `main` or `develop` branch are updated.
Additionally, documentation previews will be built for every [pull request](https://github.com/CLIMADA-project/climada_python/pulls) 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 `develop` branch.

## Local Build

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](https://climada-python.readthedocs.io/en/latest/guide/install.html#advanced-instructions).
Make sure to install the developer requirements as well.

Then, activate the `climada_env` and navigate to the `doc` directory:
```
conda activate climada_env
cd climada_python/doc
```

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.

## 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`.

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:

1. [Install Docker](https://docs.docker.com/get-docker/) on your machine.
2. Enter the top-level directory of the CLIMADA repository with your shell:

    ```
    cd climada_python
    ```
3. Instruct Docker to build an image from the `doc/create_env_doc.dockerfile`:

    ```
    docker build -f doc/create_env_doc.dockerfile -t climada_env_doc ./
    ```
4. Run a container from this image:

    ```
    docker run -it climada_env_doc
    ```
5. 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.yml` file in the CLIMADA repository, overwriting all its contents.