cerc_persistence_doc/README.md

# libs_doc

Automatic tool to create the libs' documentation

# Windows compilation instructions using Windows Subsystem for Linux (WSL2)

Open Powershell as an Administrator and run
```
wsl.exe --install
```

This will enable the Windows Subsystem for Linux and install the command line version of Ubuntu. Once finished, restart your computer. When you login again, Ubuntu will open automatically. Enter in a new username and password for the Ubuntu installation.

Update and upgrade the apt packages
```
sudo apt update && sudo apt upgrade -y
```

Next, follow the steps outlined in the [Linux compilation section](#linux-compilation) below.

Create a new directory called *cerc_docs* and navigate to the new directory
```
mkdir cerc_docs && cd cerc_docs
```

Clone the *cerc_persistence_doc* repository
```
git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence_doc
```

Clone the *cerc_persistence* repository
```
git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence
```

Navigate to the *cerc_persistence_doc* directory
```
cd cerc_persistence_doc
```

Compile the PDF
```
make latexpdf
```

The compiled *cercpersistencereferencemanual.pdf* will be created in
```
cerc_docs/cerc_persistence_doc/build/latex/
```

# Mac compilation
Open terminal and install homebrew
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Install Sphinx
```
brew install sphinx-doc
echo 'export PATH="/usr/local/opt/sphinx-doc/bin:$PATH"' >> ~/.zshrc
```

Install latexmk
```
sudo tlmgr install latexmk
```

Install BasicTeX
```
brew install --cask basictex
```

Install texlive
```
brew install texlive
```

Install Tree
```
brew install tree
```

Install ImageMagick
```
brew install imagemagick
```

Install Graphviz
```
brew install graphviz
```

Create a new directory called *cerc_docs* and navigate to the new directory
```
mkdir cerc_docs && cd cerc_docs
```

Clone the *cerc_persistence_doc* repository
```
git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence_doc
```

Clone the *cerc_persistence* repository
```
git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence
```

Navigate to the *cerc_persistence_doc* directory
```
cd cerc_persistence_doc
```

Compile the PDF
```
make latexpdf
```

The compiled *cercpersistencereferencemanual.pdf* will be created in
```
cerc_docs/cerc_persistence_doc/build/latex/
```


# Linux compilation

Some dependencies are needed in Linux systems, this manual cover only debian based distros (like Ubuntu), but the process should be similar for other Linux distributions

- Build essential

```
sudo apt install build-essential
```

- Sphinx

```
sudo apt install sphinx
```

- Latex

```
sudo apt install texlive-latex-extra latexmk
```

- Tree
```
sudo apt install tree
```

- ImageMagick
```
sudo apt install libpng-dev libjpeg-dev libtiff-dev imagemagick
```

- Graphviz
```
sudo apt install graphviz
```

Some changes are mandatory in the policymap of imagemagick (/etc/ImageMagick-6/policy.xml)

Disable security policy by commenting or deleting the following line
```
<policy domain="path"rights="none" pattern="@*"/>
```
To prevent size errors change the width and height values to 16MP
```
<policy domain="resource" name="width" value="16MP"/>
<policy domain="resource" name="height" value="16MP"/>
```