Compare commits
1 Commits
7e508f226e
...
0e30a0e63b
Author | SHA1 | Date | |
---|---|---|---|
|
0e30a0e63b |
81
README.md
81
README.md
@ -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
|
|
||||||
|
Loading…
Reference in New Issue
Block a user