new theme wtf_coop created from sphinx13, config changed to use new theme, no further adapations than filenames are done

README.md

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