forked from wtf-eg/handbuch-gen
adapted README.md to changed content of package (only sphinx stays in the repo)
This commit is contained in:
parent
e6f253447e
commit
ff122a09d7
75
README.md
75
README.md
@ -1,87 +1,34 @@
|
||||
# rtfm
|
||||
# About
|
||||
|
||||
This repo contains the sphinx configuration and the wtf theme for sphinx for the generation of the WTF handbook.
|
||||
|
||||
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
|
||||
# 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.
|
||||
# How to build
|
||||
|
||||
### 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
|
||||
``````
|
||||
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```
|
||||
|
||||
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
|
||||
The top level directory contains a Makefile,
|
||||
for generation with all output formats use
|
||||
|
||||
For generation with all tools use
|
||||
`````
|
||||
make all
|
||||
make bundle
|
||||
`````
|
||||
|
||||
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
|
||||
|
Loading…
Reference in New Issue
Block a user