Readme #15

Merged
Brain merged 6 commits from dancingCycle/handbuch-gen:readme into main 2022-11-22 21:10:22 +01:00

View File

@ -17,6 +17,14 @@ This repository accesses the required WTF handbook's content as a git submodule.
git clone --recurse-submodules https://git.wtf-eg.de/wtf-eg/handbuch-gen.git git clone --recurse-submodules https://git.wtf-eg.de/wtf-eg/handbuch-gen.git
``` ```
If you cloned this repository initially without submobules, you can always update the content of submodule directories 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.
### Python based dependencies ### Python based dependencies
In order to generate the documentation, first create a Python 3 virtual environment using the `venv` module included in Python 3: In order to generate the documentation, first create a Python 3 virtual environment using the `venv` module included in Python 3:
@ -29,7 +37,13 @@ In order to generate the documentation, first create a Python 3 virtual environm
For generating the images from PlantUML sources (`*.plantuml`), [PlantUML](https://plantuml.com/) is required. For generating the images from PlantUML sources (`*.plantuml`), [PlantUML](https://plantuml.com/) is required.
For pdf output the LaTeX builder is used, so `latex` and `pdflatex` need to be installed. For pdf output the LaTeX builder is used, so `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 texlive-latex-base texlive-latex-extra texlive-lang-german texlive-fonts-extra --no-install-recommends
```
For document generation `make` and `latexmk` is required.
Outdated
Review

Could be summarized into one apt-get command. If readability is a concern, linebreaks can be applied like this:

sudo apt-get --no-install-recommends install \
  texlive-base \
  texlive-latex-base \
  ...
Could be summarized into one `apt-get` command. If readability is a concern, linebreaks can be applied like this: ```bash sudo apt-get --no-install-recommends install \ texlive-base \ texlive-latex-base \ ... ```
### Running the document generation via make ### Running the document generation via make
@ -42,3 +56,8 @@ make bundle
The output files of the final handbook can be found in the subfolder `./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. 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```