# Studienarbeiten


(semAuth2jupyterbook)=
## semAuth 2 jupyterbook


Seit einiger Zeit erzeugen verschiedene, gut aufeinander abgestimmte Innovationen im Bereich der Software-Dokumentation inovative Impulse für die Software-Dokumentation:

* In einem Jupyter Notebook lässt sich Python-Code auf Skript-Ebene dynamisch und interaktiv entwickeln.
* Mit dem Tool jupyterbook lassen sich Jupyter Notebooks, Python-Programme und -Bibliotheken, rein textuelle Markdown-Dateien etc. elegant fürs Web und als pdf publizieren - auch mit enger Integration mit der Literaturverwaltung [Zotero](https://www.zotero.org/).
* Das Dokumentations-Framework [Diátaxis](https://diataxis.fr/) (auch bei [divio > documentation system](https://documentation.divio.com/) gibt Hinweise, wie Tutorials, How-To, Reference und Explanation aufeinander zu beziehen sind. (Dieses System wird inzwischen auch von [Ubuntu](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation) als Standard-Struktur empfohlen.)

In einem aktuell laufenden Studienprojekt entwickeln wir derzeit für unser [dsci-lab](http://jbusse.de/dsci-lab/intro.html) eine Konfiguration, die all das "ready to fly" für Bachelor-Arbeiten etc. zur Verfügung stellt.

Offene Herausforderungen:

* Die Strukturierung der Dokumentation über die jupyterbook-Konfigurationsdatei `_toc.yml` ist komplex und fehleranfällig.
* Schon leichte Umstrukturierungen der Dokumentation erfordert Anpassungen in allen Dokumenten, und ist manuell praktisch kaum zu handhaben.

Lösungsidee: Seit über 10 Jahren publiziert J.Busse seine Website aus einer [freeplane](https://www.freeplane.org/wiki/index.php/Home)-Mindmap heraus, incl. ID-Management, Link-Integrität, Überschriften-Kontrolle etc. Das zugehörige [XSLT-Skript semAuth](http://jbusse.de/semauth/) ist hässlich und kaum mehr wartbar.

Ziel der Studienprojekts ist es, leicht und schlank einige wenige Grundfunktionen von semAuth1 in Python neu zu implementieren.

Gegeben ist eine Mindmap,
* in der die Struktur der Website (aber nicht die Inhalte der einzelnen Seiten) mit semAuth-Tags deklariert wird;
* in der die einzelnen Seiteninhalte in Markdown angelegt werden

Gesucht ist eine Übersetzung dieser Mindmap in ein jupyterbook, das dann mit `jb build` in eine Website oder ein pdf-Dokument übersetzt werden kann.