manual-gen/README.md

manual-gen

Generate the manual.

Build

Checkout

This repository accesses the required manual repository as a git submodule. Therefore, make sure to check out this repository and included submodules:

git clone --recurse-submodules <git remote repository>

If you cloned this repository initially without submobules, you can always update the content of submodules with the git submodule update command. Execute the command from the main project directory:

git submodule update --init --recursive

The --init flag initializes the submodules before the update. The --recursive option searches for nested submodules and ensures they are updated too.

If new commits are available for submodules, you can always update the remote content of submudlues with the git submodule update command. Execute the command from the main project directory:

git submodule update --remote --merge

Python Dependencies

In order to generate the documentation, first create a Python 3 virtual environment using the venv module included in Python 3:

1. Create a virtual Python environment in the directory venv: python3 -m venv venv
2. Activate the virtual Python environment: source venv/bin/activate
3. Install the packages listed in requirements.txt using pip: pip install -r requirements.txt

Other Dependencies

The LaTex builder is used for PDF output. Latex and pdflatex need to be installed. On a clean (no LaTex compilation yet) operating system like GNU/Debian, the following dependencies are required to make Latex compile the sources.

sudo apt install texlive-base --no-install-recommends
sudo apt-get install texlive-latex-base --no-install-recommends
sudo apt-get install texlive-latex-extra --no-install-recommends
sudo apt-get install texlive-lang-german --no-install-recommends
sudo apt-get install texlive-fonts-extra --no-install-recommends

Make and latexmk` is required for document generation.

Generation via Make

The top level directory contains a Makefile. Tor generation with all output formats use:

make bundle

The output files of the final handbook can be found in the subfolder ./bundle. All generated intermediate artifacts and the final output files can be found in the ./build subfolder.

Clean up

1. Deactivate the virtual Python environment: deactivate
2. Clean up the build sources: make clean and rm -r build bundle