From 204abce3b42962e961f203a3abfb150d50d0b00d Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:33:59 +0200 Subject: [PATCH] Changed heading levels back to original, added some more info and cross references --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9601d21..36a359e 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,12 @@ 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 repository contains the [https://www.sphinx-doc.org/](Sphinx) configuration and the WTF theme for Sphinx for the generation of the WTF handbook. +This repository contains the [https://www.sphinx-doc.org/](Sphinx) configuration and a Sphinx theme adapted for the [https://git.wtf-eg.de/ag_kommunikation/wtf_propaganda](corporate identity of WTF cooperation). -# 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: @@ -20,7 +17,7 @@ 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 In order to generate the documentation, first create a Python 3 virtual environment using the `venv` module included in Python 3: @@ -28,12 +25,12 @@ In order to generate the documentation, first create a Python 3 virtual environm 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 @@ -41,4 +38,6 @@ The top level directory contains a Makefile, for generation with all output form make bundle ````` -The output files can then be found +The output files of the final handbook can be found in the subfolder `./bundle`. + +All generated intermediate artifacts and the final output files can be found in the `./build` subfolder.