Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| db81b65cc4 | |||
| 56c68fc085 |
1
.gitignore
vendored
@ -210,4 +210,3 @@ crowbook/wtf-handbook.pdf
|
||||
|
||||
# Plantuml binary
|
||||
plantuml.jar
|
||||
py3-sphinx
|
||||
|
||||
4
.gitmodules
vendored
@ -1,3 +1,3 @@
|
||||
[submodule "handbuch"]
|
||||
path = source/handbuch
|
||||
url = https://git.wtf-eg.de/wtf-eg/handbuch.git
|
||||
path = handbuch
|
||||
url = https://git.wtf-eg.de/ag_kommunikation/handbuch.git
|
||||
|
||||
46
Makefile
@ -1,34 +1,26 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
.PHONY: mdbook crowbook sphinx bundle
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: sphinx bundle
|
||||
all: mdbook crowbook sphinx
|
||||
|
||||
clean:
|
||||
-rm -rf build/*
|
||||
-rm -rf sphinx/build/*
|
||||
|
||||
mdbook:
|
||||
-mdbook build mdbook
|
||||
-cd mdbook; RUST_BACKTRACE=1 mdbook-epub --standalone
|
||||
|
||||
crowbook:
|
||||
crowbook crowbook/wtf-handbook.book
|
||||
|
||||
sphinx:
|
||||
$(MAKE) singlehtml epub latexpdf
|
||||
$(MAKE) -C sphinx singlehtml epub latexpdf
|
||||
|
||||
bundle: sphinx
|
||||
bundle: all
|
||||
-mkdir bundle
|
||||
cp build/epub/*.epub bundle/
|
||||
cp build/latex/*.pdf bundle/
|
||||
rsync -av --delete build/singlehtml/ bundle/html
|
||||
cp mdbook/book/epub/RTFM\ -\ Das\ WTF\ Kooperative\ Handbuch.epub bundle/mdbook_RTFM\ -\ Das\ WTF\ Kooperative\ Handbuch.epub
|
||||
cp crowbook/wtf-handbook.epub bundle/crowbook_wtf-handbook.epub
|
||||
cp crowbook/wtf-handbook.pdf bundle/crowbook_wtf-handbook.pdf
|
||||
cp crowbook/wtf-handbook.html bundle/crowbook_wtf_handbook.html
|
||||
cp sphinx/build/epub/RTFM-DasHandbuchzurWTFeG.epub bundle/sphinx_DasHandbuchzurWTFeG.epub
|
||||
cp sphinx/build/latex/rtfm-dashandbuchzurwtfeg.pdf bundle/sphinx_DasHandbuchzurWTFeG.pdf
|
||||
rsync -av --delete sphinx/build/singlehtml/ bundle/sphinx_html
|
||||
|
||||
75
README.md
@ -1,34 +1,87 @@
|
||||
# About
|
||||
|
||||
This repo contains the sphinx configuration and the wtf theme for sphinx for the generation of the WTF handbook.
|
||||
# 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.
|
||||
|
||||
# sphinx html theme for wtf coop
|
||||
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
|
||||
## 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
|
||||
`````
|
||||
|
||||
1. Create a virtual Python environment: ```python3 -m venv venv```
|
||||
2. Activate virtual Python environment: ```source venv/bin/activate```
|
||||
3. install needed packages from ```requirements.txt```: ```pip install -r requirements.txt```
|
||||
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](https://plantuml.com/).
|
||||
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 output formats use
|
||||
The top level directory contains a Makefile
|
||||
|
||||
For generation with all tools use
|
||||
`````
|
||||
make bundle
|
||||
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
|
||||
|
||||
9
crowbook/README.md
Normal file
@ -0,0 +1,9 @@
|
||||
|
||||
## Installation ##
|
||||
|
||||
````
|
||||
rustup
|
||||
cargo install crowbook
|
||||
````
|
||||
|
||||
pdf generation needs xelatex
|
||||
25
crowbook/wtf-handbook.book
Normal file
@ -0,0 +1,25 @@
|
||||
author: Autorenkollektiv
|
||||
title: RTFM - Das Handbuch für die WTF eG
|
||||
lang: de
|
||||
|
||||
## Output formats
|
||||
|
||||
# Uncomment and fill to generate files
|
||||
# output.html: some_file.html
|
||||
# output.epub: some_file.epub
|
||||
# output.pdf: some_file.pdf
|
||||
|
||||
# Or uncomment the following to generate PDF, HTML and EPUB files based on this file's name
|
||||
output: [pdf, epub, html]
|
||||
|
||||
# Uncomment and fill to set cover image (for EPUB)
|
||||
# cover: some_cover.png
|
||||
|
||||
## List of chapters
|
||||
+ ../handbuch/intro.md
|
||||
+ ../handbuch/organisation.md
|
||||
+ ../handbuch/Aufnahmeprozess.md
|
||||
+ ../handbuch/Wegweiser.md
|
||||
+ ../handbuch/Auszahlung.md
|
||||
+ ../handbuch/RaaS.md
|
||||
+ ../handbuch/FAQ.md
|
||||
1
handbuch
Submodule
8
mdbook/README.md
Normal file
@ -0,0 +1,8 @@
|
||||
|
||||
## Installation ##
|
||||
|
||||
``
|
||||
rustup
|
||||
cargo install mdbook
|
||||
cargo install mdbook-epub
|
||||
````
|
||||
11
mdbook/book.toml
Normal file
@ -0,0 +1,11 @@
|
||||
[book]
|
||||
authors = ["Autorenkollektiv"]
|
||||
language = "de"
|
||||
multilingual = false
|
||||
src = "src"
|
||||
title = "RTFM - Das WTF Kooperative Handbuch"
|
||||
|
||||
[output.html]
|
||||
mathjax-support = true
|
||||
|
||||
[output.epub]
|
||||
9
mdbook/src/SUMMARY.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Inhaltsverzeichnis
|
||||
|
||||
- [Wichtige Links](../../Handbuch/intro.md)
|
||||
- [Organisation](../../handbuch/organisation.md)
|
||||
- [Aufnahmeprozess](../../Handbuch/Aufnahmeprozess.md)
|
||||
- [Wegweiser für neue Mitglieder](../../Handbuch/Wegweiser.md)
|
||||
- [Auszahlung](../../Handbuch/Auszahlung.md)
|
||||
- [Rechnung as a Service (RaaS)](../../Handbuch/RaaS.md)
|
||||
- [Häufige Fragen](../../Handbuch/FAQ.md)
|
||||
20
sphinx/Makefile
Normal file
@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
5
sphinx/README.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Installation
|
||||
|
||||
1. Virtuelle Pythonumgebung erstellen: ```python3 -m venv venv```
|
||||
2. Virtuelle Umgebung aktivieren: ```source venv/bin/activate```
|
||||
3. Pakete aus ```requirements.txt``` installieren: ```pip install -r requirements.txt```
|
||||
|
Before Width: | Height: | Size: 134 KiB After Width: | Height: | Size: 134 KiB |
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 11 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
@ -24,7 +24,7 @@ copyright = '2021, diverse'
|
||||
author = 'Autorenkollektiv'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '0.0.5'
|
||||
release = '0.0.4'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
1
sphinx/source/handbuch
Symbolic link
@ -0,0 +1 @@
|
||||
../../handbuch/
|
||||
@ -14,8 +14,8 @@ RTFM - Das Handbuch zur wtf Kooperative eG
|
||||
handbuch/organisation.md
|
||||
handbuch/Aufnahmeprozess.md
|
||||
handbuch/Wegweiser.md
|
||||
handbuch/RaaS.md
|
||||
handbuch/Auszahlung.md
|
||||
handbuch/RaaS.md
|
||||
handbuch/FAQ.md
|
||||
|
||||
Indices and tables
|
||||
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 78 KiB |
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 80 KiB |
|
Before Width: | Height: | Size: 79 KiB After Width: | Height: | Size: 79 KiB |
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 80 KiB |
|
Before Width: | Height: | Size: 81 KiB After Width: | Height: | Size: 81 KiB |
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 78 KiB |
|
Before Width: | Height: | Size: 91 KiB After Width: | Height: | Size: 91 KiB |
|
Before Width: | Height: | Size: 66 KiB After Width: | Height: | Size: 66 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |