rendering from markdown documents for handbook with different documentation generators to html, pub and pdf
Go to file
2021-08-16 19:42:46 +02:00
crowbook updated to new version of handbuch submodule (new md files added) 2021-08-16 19:42:46 +02:00
handbuch@4cc1f50802 updated to new version of handbuch submodule (new md files added) 2021-08-16 19:42:46 +02:00
mdbook updated to new version of handbuch submodule (new md files added) 2021-08-16 19:42:46 +02:00
sphinx updated to new version of handbuch submodule (new md files added) 2021-08-16 19:42:46 +02:00
.gitignore outputs added to ignore list 2021-08-01 18:23:06 +02:00
.gitmodules added handbuch as submodule and refactored mdbook config for this 2021-07-28 20:40:02 +02:00
LICENSE Initial commit 2021-07-12 10:07:43 +02:00
Makefile all result are copied into one (bundle) dir as make target 2021-08-01 18:14:46 +02:00
README.md „README.md“ ändern 2021-08-05 22:29:04 +02:00

rtfm

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.

It contains a configuration for three different generators:

  • mdbook and mdbook-epub
  • crowbook
  • sphinx

sphinx html theme for wtf coop

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

How to build

rust based tools mdbook and crowbook

For building you need a rust installation. This can be achieved by using the installer from https://rustup.rs

After installing the rust toolchain for your platform you have to install the needed tools:

cargo install mdbook
cargo install mdbook-epub
cargo install crowbook

Crowbook needs xelatex for building the pdf outputs.

python based - sphinx

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

 python -m venv py3-sphinx

Now “activate” the environment. Look for the name of the virtual environment enclosed in parenthesis after activation.

 source py3-sphinx/bin/activate

Expected Output

 (py3-sphinx) $

In the virtual environment install the following modules with pip:

 (py3-sphinx) $ pip install sphinx3 sphinxcontrib-plantuml myst-parser

For generating the images from plantuml-sources it needs also Plantuml. For pdf output the latex builder is used, so it needs also an installed latex and pdflatex.

Running the document generation via make

The top level directory contains a Makefile

For generation with all tools use

make all

For generation with single tool use:

make mdbook [crowbook sphinx]

Issues

mdbook - rendering problem with current inputs

sphinx - Problems rendering latex with .svg image(organigramm.svg)

mumble and mailto links are not rendered correctly tbd have an eye on all outputs

TODO

  • complete wtf coop HTML theme
  • add frontpage with wtf coop CI
  • adapt generated pdf to WTF design
  • unify Title and authors in the configurations