From bef5199114b1ccc6f0c648a0cc8174fd917b7a17 Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:28:10 +0200 Subject: [PATCH] Update README --- README.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index c506561..9601d21 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,17 @@ # 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 the WTF handbook in various output formats (HTML, epub and pdf) from the [https://git.wtf-eg.de/wtf-eg/handbuch-gen](git repository for the WTF handbook). The handbuch sources are included as git submodule. -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. +This repository contains the [https://www.sphinx-doc.org/](Sphinx) configuration and the WTF theme for Sphinx for the generation of the WTF handbook. -# 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 -### Checkout with submodules +## Checkout with submodules This repository accesses the required WTF handbook's content as a git submodule. Therefore, make sure to check out this repository including its submodule: @@ -22,24 +20,25 @@ This repository accesses the required WTF handbook's content as a git submodule. git clone --recurse-submodules https://git.wtf-eg.de/wtf-eg/handbuch-gen.git ``` -### Python based dependencies +## Python based dependencies -First create a Python 3 virtual environment using the venv module included with Python 3. +In order to generate the documentation, first create a Python 3 virtual environment using the `venv` module included in Python 3: -1. Create a virtual Python environment in the directory `venv` using the Python module `venv`: ```python3 -m venv venv``` -2. Activate the virtual Python environment: ```source venv/bin/activate``` -3. Install the packages listed in [./requirements.txt](requirements.txt) using `pip`: ```pip install -r requirements.txt``` +1. Create a virtual Python environment in the directory `venv`: ```python3 -m venv venv``` +1. Activate the virtual Python environment: ```source venv/bin/activate``` +1. Install the packages listed in [./requirements.txt](requirements.txt) using `pip`: ```pip install -r requirements.txt``` -### Other dependencies +## Other dependencies For generating the images from PlantUML sources (`*.plantuml`), [Plantuml](https://plantuml.com/) is required. For pdf output the latex builder is used, so latex and pdflatex need to be installed. -### Running the document generation via make +## Running the document generation via make -The top level directory contains a Makefile, -for generation with all output formats use +The top level directory contains a Makefile, for generation with all output formats use ````` make bundle ````` + +The output files can then be found