diff --git a/README.md b/README.md index e074870..cdf1a6c 100644 --- a/README.md +++ b/README.md @@ -21,3 +21,45 @@ 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. + +## 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``` +1. Activate the virtual Python environment: ```source venv/bin/activate``` +1. Install the packages listed in [requirements.txt](./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``` diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..d4eb051 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +sphinxcontrib-plantuml +myst-parser