Studienarbeiten
Inhalt
Studienarbeiten¶
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.
Das Dokumentations-Framework Diátaxis (auch bei divio > documentation system gibt Hinweise, wie Tutorials, How-To, Reference und Explanation aufeinander zu beziehen sind. (Dieses System wird inzwischen auch von Ubuntu als Standard-Struktur empfohlen.)
In einem aktuell laufenden Studienprojekt entwickeln wir derzeit für unser dsci-lab 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.ymlist 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-Mindmap heraus, incl. ID-Management, Link-Integrität, Überschriften-Kontrolle etc. Das zugehörige XSLT-Skript 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.