handbuch-gen/README.md

[![Build Status](https://drone.wtf-eg.de/api/badges/wtf-eg/handbuch-gen/status.svg)](https://drone.wtf-eg.de/wtf-eg/handbuch-gen)

# About 

This repo contains the sphinx configuration and the wtf theme for sphinx for the generation of the WTF handbook.

this project is an experiment of how to generate html, epub and pdf
from the git repository for the WTF handbook.
The handbuch sources are included as git submodule.

# sphinx html theme for wtf coop 

the sphinx build uses an adapted sphinx theme for the WTF cooperatives CI.

# How to build

### Checkout with submodules

This repository accesses the required WTF handbook's content as a git submodule. Therefore, make sure to check out this repository including its submodule:

```
git clone --recurse-submodules https://git.wtf-eg.de/wtf-eg/handbuch-gen.git
```

### Python based dependencies

First create a Python 3 virtual environment using the venv module included with Python 3.

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

### Other dependencies

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.

### Running the document generation via make

The top level directory contains a Makefile, 
for generation with all output formats use

`````
make bundle
`````