2. Documentation

2.1. Building documentation

The user and developer guides are built automatically via Read The Docs. When changing the guides, build the html and pdf files locally before committing changes to the repository.

Prerequisites

The following shows how to create the html and pdf files for the user/developer guide. First, install the required prerequisites. Install python3 and make sure that pip (third-party Python packages) is installed. If you have an old version of, e.g., Ubuntu visit this website.

sudo apt install python3-pip

Navigate to the documentation folder from the PICLas top level directory

cd docs/documentation

Run pip to install the required extensions and packages for compiling the user guide (only once)

python3 -m pip install --exists-action=w --no-cache-dir -r requirements.txt

Make sure that latexmk is installed on the system for compiling the PDF version of the user guide. For Ubuntu, follow this link for installation.

sudo apt-get install latexmk

HTML Version

Compile the html version of the user guide via

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

Check that no errors occur during compilation and then navigate to the created html files

cd _build/html

Open index.html to see if everything has worked out correctly (e.g. with your favourite browser). Note that you can simply run the script buildHTML.sh in the documentation directory for this task.

PDF Version

Next, create the pdf output.

python3 -m sphinx -b latex -D language=en -d _build/doctrees . _build/latex

and switch into the output directory

cd _build/latex

Finally, compile the pdf file

latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=piclas -interaction=nonstopmode

and check if the pdf exists

ls _build/latex/piclas.pdf

Note that you can simply run the script buildPDF.sh in the documentation directory for this task.

2.2. Writing documentation

2.2.1. Figures

Graphics are supported as long as their size is not above 1 MB, recommended size is below 100 KB. The conversion of PDF plots/graphics produced with pgfplots/tikz can be performed via terminal using the libvips package available for most distributions

sudo apt install libvips-dev
vips copy example.pdf[dpi=150] example.jpg[Q=90,strip]

Modify dpi=150 to scale the PDF and Q=90 (between 0 and 100) to change the quality of the JPEG. Vector graphics might give better quality using SVG as the end format by converting from PDF

pdf2svg example.pdf example.svg