The Handbook is published at https://handbook.climaax.eu

If you'd like to develop and/or build this Climate Risk Assesment book, you should:

1. Clone this repository

    git clone git@github.com:CLIMAAX/crabook.git

2. Go to the the crabook/ directory that was created by git in the previous step

   cd crabook

3. Create a Python or Conda virtual environment (example for Conda)

    conda create -n crabook python=3.11 pip

4. Activate the environment

   conda activate crabook

5. Install the libraries, choose:

   pip install -r requirements.txt

   installs only the packages required to build the book, while

   pip install -r requirements-dev.txt

   additionally installs packages for the development of some components of the book, but which are not required during building.
6. Find the markdown files and edit what you need.
7. Remove any existing builds by running

   jupyter-book clean crabook/

8. Finally build the book

   jupyter-book build crabook/

A fully-rendered HTML version of the book will be built in crabook/_build/html/.

Open the file crabook/_build/html/intro.html and navigate to the material you changed to check if everything is as expected.

Once you're happy with the changes, create a new branch, commit your changes and send us a pull request if you'd like to contribute.

The Python/Conda environment is needed only for building the book, so you can activate it after editing the files.

1. Edit the book's source files located in the crabook/ directory

   cd crabook/crabook

2. Activate the environment

    conda activate crabook

3. Remove any existing builds by running

   jupyter-book clean crabook/

4. Finally build the book

   jupyter-book build crabook/

TLDR: To have a page show up in our production version of the CRA book, it has to be added to crabook/_toc_prod.yml.

The build process on GitHub in .github/workflows/build-deploy-book.yml contains a step to detect the repository it is started from. If this repository is CLIMAAX/crabook, the default table of contents crabook/_toc.yml is replaced by the file crabook/_toc_prod.yml. This enables us to hide pages in the production repository that are still under development in our test repository without having to edit the table of contents file back-and-forth every time changes are pushed to production.

We welcome and recognize all contributions. You can see a list of current contributors in the contributors tab.

This project is created using the excellent open source Jupyter Book project and the executablebooks/cookiecutter-jupyter-book template.

Apache-2.0 OR CC-BY-4.0

The CLIMAAX CRA Handbook is available under both the Apache License 2.0 or the Creative Commons Attribution 4.0 International license.