rendering of wtf handbook with sphinx
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Brain ab3190dcf1
Update sources
7 months ago
source Update sources 7 months ago
theme fix: got rid of woff fonts to create minmal size build 2 years ago
.drone.yml Automatically determine version 9 months ago
.gitignore removed crowbook and mdbook configand moved sphinx dirs one level up 2 years ago
.gitmodules Clone submodule via SSH 10 months ago
LICENSE Initial commit 2 years ago
Makefile Initial build config for Drone 10 months ago Merge pull request 'Readme' (#15) from dancesWithCycles/handbuch-gen:readme into main 7 months ago
requirements.txt fix: copied sphinx_rtd_theme to further shrink filesize 2 years ago

Build Status


This project is an experiment of how to generate the WTF handbook in various output formats (HTML, epub and pdf) from the git repository for the WTF handbook. The handbuch sources are included as git submodule.

This repository contains the Sphinx configuration and a Sphinx theme adapted for the corporate identity of WTF cooperation.

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

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

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

For generating the images from PlantUML sources (*.plantuml), PlantUML is required.

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.

Running the document generation via make

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

make bundle

In order to automatically determine the version string from the latest Git tag, execute the following command before calling make:

export SPHINXOPTS="-D version=$(git -C source/handbuch describe --tags --abbrev=0) -D release=$(git -C source/handbuch describe --tags)"

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