From ff122a09d7b609561571c75ac8133652891ef300 Mon Sep 17 00:00:00 2001 From: Gulliver Date: Thu, 16 Sep 2021 09:21:56 +0200 Subject: [PATCH] adapted README.md to changed content of package (only sphinx stays in the repo) --- README.md | 75 ++++++++----------------------------------------------- 1 file changed, 11 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 2fb5387..d21d7aa 100644 --- a/README.md +++ b/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