From d155dbba15409fc3cdb5402ba65b18a34ee4f6a5 Mon Sep 17 00:00:00 2001 From: Kristof Schroeder Date: Mon, 25 Mar 2024 21:50:16 +0100 Subject: [PATCH 1/3] Update instructions regarding installation of aditional dependencies for building documentation locally --- CONTRIBUTING.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a733331a..00ff508a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,9 +54,18 @@ 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. +Using homebrew on OSX you can use + +```shell +brew install cairo freetype libffi libjpeg libpng zlib +``` +for this. For instructions on Linux and Windows, see 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 From b560c16c92f2d551fe9b09f7edc451ac1a924603 Mon Sep 17 00:00:00 2001 From: Kristof Schroeder Date: Mon, 25 Mar 2024 21:51:34 +0100 Subject: [PATCH 2/3] Add a hint to CONTRIBUTING.md Documentation section for fixing a linking issue for OSX+cairo via homebrew --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00ff508a9..7396b5471 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -255,6 +255,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: @@ -272,6 +276,18 @@ mkdocs serve This will rebuild the documentation on changes to `.md` files inside `docs`, notebooks and python files. +It is possible, that the cairo lib file is not properly linked, when installed +via homebrew on OSX. 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 From 7f8b14bd09f848c1d7eb32dbc3f97dd53104a13e Mon Sep 17 00:00:00 2001 From: Kristof Schroeder Date: Tue, 26 Mar 2024 14:12:43 +0100 Subject: [PATCH 3/3] Remove explicit install command for macOS and refer to mkdocs-material documentation, apply suggestion from review --- CONTRIBUTING.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb1cd6219..d2f47395f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,14 +60,9 @@ pip install -e . ``` In order to build the documentation locally (which is done as part of the tox -suite) you need to install additional non-python dependencies. -Using homebrew on OSX you can use +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). -```shell -brew install cairo freetype libffi libjpeg libpng zlib -``` -for this. For instructions on Linux and Windows, see 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 @@ -282,8 +277,8 @@ mkdocs serve This will rebuild the documentation on changes to `.md` files inside `docs`, notebooks and python files. -It is possible, that the cairo lib file is not properly linked, when installed -via homebrew on OSX. In this case you might encounter an error like this +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