IGMAS+ Documentation

This project is devoted to maintenance of the online IGMAS+ documentation:
https://igmas.git-pages.gfz-potsdam.de/igmas-docs

It is based on GitLab Pages and MkDocs with Material theme.

GitLab CI

This project's static Pages are built by GitLab CI, following the steps defined in .gitlab-ci.yml.

Contributing

Please refer to the contributing guidelines.

Installation

To work with this project, you need to install MkDocs and the required plugins and extensions.

Clone the repository

To clone the repository, you need to have Git installed on your system.

1. Clone or download this project:

   git clone https://git.gfz-potsdam.de/igmas/igmas-docs.git

2. Open the project directory (igmas-docs by default)

   cd igmas-docs

3. Check out the devel branch:

   git checkout devel

Note: If you are using Windows, you may need to use Git Bash or Windows Terminal to run the commands above.

You can also download the project as a ZIP file and extract it to your desired location.

Installing MkDocs using pip

In order to install MkDocs and the required plugins and extensions, you need to have Python and pip installed on your system.

Pythion 3.7 or higher is required (3.11 is recommended).

To install required packages, plugins and extensions using pip, run the following command in your terminal:

pip install -r requirements.txt

Note: if you are installing with pip and want to use the PDF generation feature, you need to install additional dependencies as described in the Installing additional dependencies section.

Installing MkDocs using conda

If you are using Miniconda or Miniforge, you can also install MkDocs and the required plugins and extensions using conda.

Create a new environment with the required packages using the environment.yml file:

conda env create -f environment.yml

or simply run:

conda env create

This will create a new conda environment named igmas-docs with the required packages and dependencies.

To activate the environment, run:

conda activate igmas-docs

Installing additional dependencies

There are some additional dependencies that are required for rendering the PDF version of the documentation and for some plugins to work correctly.

GTK

GTK (GIMP Toolkit) is required for rendering the PDF version of the documentation. It is used by the mkdocs-with-pdf plugin.

On Windows, make sure to install GTK (see troubleshooting).

And then run additionally:

pip install --force-reinstall --prefer-binary cffi cairocffi pillow

Pandoc

Pandoc is used for rendering citations and bibliography in the documentation. It is required for the mkdocs-bibtex plugin to work correctly. It can also be used to generate PDF files from the documentation or to generally convert Markdown files to other formats.

Pandoc is installed automatically when using conda or as described above because it is included in the environment.yml file.

If using pip, you need to install it manually.

On Linux, you can install it using your package manager, for example on Ubuntu:

sudo apt install pandoc

or use the script provided in this repository:

./scripts/install_pandoc.sh

On Windows, you can download the installer from the Pandoc website and follow the instructions.

Check MkDocs version

To check if MkDocs is installed correctly, run the following command in your terminal:

mkdocs --version

This should print the version of MkDocs.

To check MkDocs Material version, run:

pip show mkdocs-material

View and build locally

To see the documentation website locally, run the following command in your terminal:

mkdocs serve

or:

./scripts/preview.sh

The website can be accessed under localhost:8000

To generate the website html pages run:

mkdocs build

Help

Run mkdocs help to print the help message.

Build PDF

If you want to render the PDF of the website, ensure that the environment variable WITH_PDF is set to true before running mkdocs:

Note: You need a browser in a headless mode in order to render mathematic equations:

On Ubuntu you can use the script to install headless chromium:

./scripts/install_chromium.sh

Then, to build:

WITH_PDF=true mkdocs build

On Windows just install Google Chrome (you may need to adjust the path to Chrome in mkdocs.yml)

To build on Windows in command line, you can use:

set WITH_PDF=true
mkdocs build

Or in PowerShell:

$env:WITH_PDF = "true"
mkdocs build

Read more at MkDocs documentation and take into account the additional dependencies.

Updating packages

To update all packages, run again

pip install --upgrade --force-reinstall -r requirements.txt
pip install --force-reinstall --prefer-binary cffi cairocffi pillow

Troubleshooting

1. OSError: no library called "cairo-2" was found

   This is quite an annoying dependency problem because cairocffi is not built for windows, you need the additional dependency as explained there: https://cairocffi.readthedocs.io/en/stable/overview.html#installing-cairo-on-windows

   A quicker solution is to do the following: use pipwin which installs from an unofficial repository https://www.lfd.uci.edu/~gohlke/pythonlibs/#pycairo:

   pip install pipwin
   pipwin install cairocffi

   Solution is taken from here.

   Alternatively you may try to reinstall packages while preferring binary versions:

   pip install --force-reinstall --prefer-binary cffi cairocffi pillow

2. OSError: cannot load library 'gobject-2.0'

   Additional dependency is needed on Windows. Install GTK3 and ensure the path to it saved in a system environment variable Path in Windows.

3. CSS is missing!

   That means two things: Either that you have wrongly set up the CSS URL in your templates, or your static generator has a configuration option that needs to be explicitly set in order to serve static assets under a relative URL.

4. AttributeError: property 'text' of 'Tag' object has no setter

   PDF creation is not working with the following message:

     ...  mkdocs_with_pdf\generator.py", line 381, in _render_js     
        tag.text = self._mixed_script     
        ^^^^^^^^ 
   AttributeError: property 'text' of 'Tag' object has no setter

   Reinstall beautifulsoup4:

   pip install --force-reinstall beautifulsoup4==4.9.3

   Reason: changes on tag introduced in beautifulsoup4 v4.10+