f53c84afeb
* feature/wtf_coop_theme: feat: updated handbuch docs: reduced install efforts with creation of requirements.txt chore: added plantuml.jar to .gitignore feat: 1st wtf_coop theme based on read the docs fix: whitespace feat: updated handbuch feat: updated handbuch feat: start over clean fix: whitespace updated submodule handbuch fix: reduced maxdepth of index to 2 to reduce clutter Makefile adapted to changed pdf filename (changed title) changed title, authors and release version initial sphinx settings for epub (cover page contains only logo for now) initial settings for wtf cooperative latex CI added theme adapted to wtf CI, logo included, links in header changed to wtf service urls new theme wtf_coop created from sphinx13, config changed to use new theme, no further adapations than filenames are done # Conflicts: # sphinx/source/conf.py |
||
|---|---|---|
| crowbook | ||
| handbuch@b87f001084 | ||
| mdbook | ||
| sphinx | ||
| .gitignore | ||
| .gitmodules | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| requirements.txt | ||
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)
problems rendering links not starting with http(s)
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