Merge pull request #546 from aai-institute/doc/544-mkdocs-cairo-mac-fix

Doc/544 mkdocs cairo mac fix

CONTRIBUTING.md

@@ -60,9 +60,13 @@ pip install -e .
 ```
 
 In order to build the documentation locally (which is done as part of the tox
-suite) [pandoc](https://pandoc.org/) is required. Except for OSX, it should be installed
-automatically as a dependency with `requirements-docs.txt`. Under OSX you can
-install pandoc (you'll need at least version 2.11) with:
+suite) you need to install additional non-python dependencies as described in
+the [documentation of mkdocs-material](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics).
+
+In addition, [pandoc](https://pandoc.org/) is required. Except for OSX, 
+it should be installed automatically as a dependency with 
+`requirements-docs.txt`. Under OSX you can install pandoc 
+(you'll need at least version 2.11) with:
 
 ```shell
 brew install pandoc
@@ -252,6 +256,10 @@ API documentation and examples from notebooks are built with
 Notebooks are an integral part of the documentation as well, please read
 [the section on notebooks](#notebooks) above.
 
+If you want to build the documentation locally, please make sure you followed
+the instructions in the section 
+[Setting up your environment](#setting-up-your-environment).
+
 Use the following command to build the documentation the same way it is
 done in CI:
 
@@ -269,6 +277,18 @@ mkdocs serve
 This will rebuild the documentation on changes to `.md` files inside `docs`,
 notebooks and python files.
 
+On OSX, it is possible that the cairo lib file is not properly linked when installed
+via homebrew. In this case you might encounter an error like this
+```shell
+OSError: no library called "cairo-2" was found
+no library called "cairo" was found
+no library called "libcairo-2" was found
+```
+when calling `mkdocs build` or `mkdocs serve`. This can be resolved via setting
+the environment variable `DYLD_FALLBACK_LIBRARY_PATH`:
+```shell
+export DYLD_FALLBACK_LIBRARY_PATH=$DYLD_FALLBACK_LIBRARY_PATH:/opt/homebrew/lib
+```
 
 ### Adding new pages