From dde5d5a7321768e3faa2e61349eb5ad99806bcb2 Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 18:12:26 +0200 Subject: [PATCH 1/8] Add info how to checkout this repo properly --- README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d21d7aa..7bcde10 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,23 @@ 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. +from the git repository for the WTF handbook. The handbuch sources are included as git submodule. # sphinx html theme for wtf coop -the sphinx build uses an adapted sphinx theme for the wtf cooperatives CI. +the sphinx build uses an adapted sphinx theme for the WTF cooperatives CI. # How to build +### 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: + +``` +git clone --recurse-submodules https://git.wtf-eg.de/wtf-eg/handbuch-gen.git +``` + ### python based - sphinx First create a Python 3 virtual environment using the venv module included with Python 3. -- 2.30.2 From 62ab2378e0bb6267a1bd0afb87a5365d72aaddba Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 21:48:28 +0200 Subject: [PATCH 2/8] Add tiny comments to explain Python's venv module --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7bcde10..e615ab7 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,9 @@ git clone --recurse-submodules https://git.wtf-eg.de/wtf-eg/handbuch-gen.git First create a Python 3 virtual environment using the venv module included with Python 3. -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``` +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 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. -- 2.30.2 From 427fc4577d5761c1e058e00ce1a8517998958541 Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 21:53:49 +0200 Subject: [PATCH 3/8] Change README section with dependencies --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e615ab7..56b2f3f 100644 --- a/README.md +++ b/README.md @@ -20,22 +20,23 @@ 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 - sphinx +### Python based dependencies First create a Python 3 virtual environment using the venv module included with 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 needed packages from ```requirements.txt```: ```pip install -r requirements.txt``` +3. Install the packages listed in [./requirements.txt](requirements.txt) using `pip`: ```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. +### 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 The top level directory contains a Makefile, -for generation with all output formats use +for generation with all output formats use ````` make bundle -- 2.30.2 From 8be828dbe46307611774bf1ecb089bc62159e13b Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:28:10 +0200 Subject: [PATCH 4/8] Update README --- README.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 56b2f3f..2064667 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,16 @@ # 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: @@ -20,24 +18,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 -- 2.30.2 From 26cb5fded4c493a6e3d80ead67bcb2d3c1e023ea Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:33:59 +0200 Subject: [PATCH 5/8] 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 2064667..b86c476 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,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: @@ -18,7 +15,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: @@ -26,12 +23,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 @@ -39,4 +36,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. -- 2.30.2 From 5ae1167d4a1c61b22004c0c43a20ade4e2c4c5cf Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:36:06 +0200 Subject: [PATCH 6/8] Fixing the Markdown link syntax (ouch) --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b86c476..e292d97 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # About -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 the WTF handbook in various output formats (HTML, epub and pdf) from the [git repository for the WTF handbook](https://git.wtf-eg.de/wtf-eg/handbuch-gen). The handbuch sources are included as git submodule. -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). +This repository contains the [Sphinx](https://www.sphinx-doc.org/) configuration and a Sphinx theme adapted for the [corporate identity of WTF cooperation](https://git.wtf-eg.de/ag_kommunikation/wtf_propaganda). # How to build @@ -21,7 +21,7 @@ In order to generate the documentation, first create a Python 3 virtual environm 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``` +1. Install the packages listed in [requirements.txt](./requirements.txt) using `pip`: ```pip install -r requirements.txt``` ### Other dependencies -- 2.30.2 From 96de477078e41bf7f32a0cdbefce4b7874fbf297 Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:36:31 +0200 Subject: [PATCH 7/8] Fix link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e292d97..e2d5895 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # About -This project is an experiment of how to generate the WTF handbook in various output formats (HTML, epub and pdf) from the [git repository for the WTF handbook](https://git.wtf-eg.de/wtf-eg/handbuch-gen). The handbuch sources are included as git submodule. +This project is an experiment of how to generate the WTF handbook in various output formats (HTML, epub and pdf) from the [git repository for the WTF handbook](https://git.wtf-eg.de/wtf-eg/handbuch). The handbuch sources are included as git submodule. This repository contains the [Sphinx](https://www.sphinx-doc.org/) configuration and a Sphinx theme adapted for the [corporate identity of WTF cooperation](https://git.wtf-eg.de/ag_kommunikation/wtf_propaganda). -- 2.30.2 From b3883901eac9ff612d42714badb4d8add4997490 Mon Sep 17 00:00:00 2001 From: maehw Date: Sat, 23 Oct 2021 22:39:29 +0200 Subject: [PATCH 8/8] Final corrections in README --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e2d5895..61f01a4 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,9 @@ In order to generate the documentation, first create a Python 3 virtual environm ### 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. +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 -- 2.30.2