Compare commits

..

1 Commits

View File

@ -1,75 +1,26 @@
# rtfm # rtfm
this project is an experiment of how to generate html, epub and pdf this projects is an experiment of how to generate html, epub and pdf
from the git repository for the WTF Handbook. from the git repository for the WTF Handbook.
The handbuch sources are included as git submodule. The handbuch sources are inclued as git submodule.
It contains a configuration for three different generators: It contains a configuration for three different generators:
- mdbook and mdbook-epub
- crowbook
- sphinx
### sphinx html theme for wtf coop ## mdbook and mdbook-epub
the sphinx build uses an adapted sphinx theme for the wtf cooperatives CI. tbd more details on README.md in mdbook directory
## crowbook
tbd more details on README.md in crowbook directory
## sphinx
tbd more details on README.md in sphinx directory
## How to build ## How to build
### rust based tools mdbook and crowbook tbd
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](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 tools use
`````
make all
`````
For generation with single tool use:
`````
make mdbook [crowbook sphinx]
`````
## Issues ## Issues
### mdbook - rendering problem with current inputs ### mdbook - rendering problem with current inputs
@ -81,7 +32,5 @@ mumble and mailto links are not rendered correctly
tbd have an eye on all outputs tbd have an eye on all outputs
## TODO ## TODO
- [ ] complete wtf coop HTML theme
- [ ] add frontpage with wtf coop CI ### unify Title and authors in the configurations
- [ ] adapt generated pdf to WTF design
- [ ] unify Title and authors in the configurations